diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-11 08:17:27 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-11 08:17:27 +0000 |
| commit | f215e02bf85f68d3a6106c2a1f4f7f063f819064 (patch) | |
| tree | 6bb5b92c046312c4e95ac2620b10ddf482d3fa8b /doc | |
| parent | Initial commit. (diff) | |
| download | virtualbox-f215e02bf85f68d3a6106c2a1f4f7f063f819064.tar.xz virtualbox-f215e02bf85f68d3a6106c2a1f4f7f063f819064.zip | |
Adding upstream version 7.0.14-dfsg.upstream/7.0.14-dfsg
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc')
228 files changed, 105358 insertions, 0 deletions
diff --git a/doc/.scm-settings b/doc/.scm-settings new file mode 100644 index 00000000..d5027a47 --- /dev/null +++ b/doc/.scm-settings @@ -0,0 +1,46 @@ +# $Id: .scm-settings $ +## @file +# Source code massager settings for the docs. +# + +# +# Copyright (C) 2010-2023 Oracle and/or its affiliates. +# +# This file is part of VirtualBox base platform packages, as +# available from https://www.virtualbox.org. +# +# 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, in version 3 of the +# License. +# +# 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, see <https://www.gnu.org/licenses>. +# +# SPDX-License-Identifier: GPL-3.0-only +# + +/*.html: --treat-as plaintext +/*.rtf: --treat-as binary +/*.doc: --treat-as binary +/*.odt: --treat-as binary +/*.ods: --treat-as binary +/*.odg: --treat-as binary +/*.sxi: --treat-as binary +/*.vpp: --treat-as binary +/*.wiki: --treat-as plaintext + +# Abusing --external-copyright. +/*.txvpck: --treat-as xml --external-copyright --no-convert-eol +/*.txvStateDiagram20: --treat-as xml --external-copyright --no-convert-eol +/*.txvComponentDiagram20: --treat-as xml --external-copyright --no-convert-eol +/*.xmi: --treat-as xml --external-copyright --no-convert-eol +/*.tpx: --treat-as xml --external-copyright --no-convert-eol +/*.graphml: --treat-as xml --external-copyright --no-convert-eol + +/*.iuml: --treat-as plaintext --add-action copyright-tick-style diff --git a/doc/License-gpl-2.html b/doc/License-gpl-2.html new file mode 100644 index 00000000..ae5e2d0e --- /dev/null +++ b/doc/License-gpl-2.html @@ -0,0 +1,353 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<!-- Translation from RTF performed by UnRTF, version 0.20.1 --> +<!-- document uses ANSI character set --> +<!-- font table contains 8 fonts total --> +<!-- creation date: --> +<!-- revision date: --> +<!-- last printed: --> +<!-- comments: StarWriter --> +</head> +<body> + GNU GENERAL PUBLIC LICENSE<br> + Version 2, June 1991<br> +<br> + Copyright (C) 1989, 1991 Free Software Foundation, Inc.,<br> + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA<br> + Everyone is permitted to copy and distribute verbatim copies<br> + of this license document, but changing it is not allowed.<br> +<br> + Preamble<br> +<br> + The licenses for most software are designed to take away your<br> +freedom to share and change it. By contrast, the GNU General Public<br> +License is intended to guarantee your freedom to share and change free<br> +software--to make sure the software is free for all its users. This<br> +General Public License applies to most of the Free Software<br> +Foundation's software and to any other program whose authors commit to<br> +using it. (Some other Free Software Foundation software is covered by<br> +the GNU Lesser General Public License instead.) You can apply it to<br> +your programs, too.<br> +<br> + When we speak of free software, we are referring to freedom, not<br> +price. Our General Public Licenses are designed to make sure that you<br> +have the freedom to distribute copies of free software (and charge for<br> +this service if you wish), that you receive source code or can get it<br> +if you want it, that you can change the software or use pieces of it<br> +in new free programs; and that you know you can do these things.<br> +<br> + To protect your rights, we need to make restrictions that forbid<br> +anyone to deny you these rights or to ask you to surrender the rights.<br> +These restrictions translate to certain responsibilities for you if you<br> +distribute copies of the software, or if you modify it.<br> +<br> + For example, if you distribute copies of such a program, whether<br> +gratis or for a fee, you must give the recipients all the rights that<br> +you have. You must make sure that they, too, receive or can get the<br> +source code. And you must show them these terms so they know their<br> +rights.<br> +<br> + We protect your rights with two steps: (1) copyright the software, and<br> +(2) offer you this license which gives you legal permission to copy,<br> +distribute and/or modify the software.<br> +<br> + Also, for each author's protection and ours, we want to make certain<br> +that everyone understands that there is no warranty for this free<br> +software. If the software is modified by someone else and passed on, we<br> +want its recipients to know that what they have is not the original, so<br> +that any problems introduced by others will not reflect on the original<br> +authors' reputations.<br> +<br> + Finally, any free program is threatened constantly by software<br> +patents. We wish to avoid the danger that redistributors of a free<br> +program will individually obtain patent licenses, in effect making the<br> +program proprietary. To prevent this, we have made it clear that any<br> +patent must be licensed for everyone's free use or not licensed at all.<br> +<br> + The precise terms and conditions for copying, distribution and<br> +modification follow.<br> +<br> + GNU GENERAL PUBLIC LICENSE<br> + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION<br> +<br> + 0. This License applies to any program or other work which contains<br> +a notice placed by the copyright holder saying it may be distributed<br> +under the terms of this General Public License. The "Program", below,<br> +refers to any such program or work, and a "work based on the Program"<br> +means either the Program or any derivative work under copyright law:<br> +that is to say, a work containing the Program or a portion of it,<br> +either verbatim or with modifications and/or translated into another<br> +language. (Hereinafter, translation is included without limitation in<br> +the term "modification".) Each licensee is addressed as "you".<br> +<br> +Activities other than copying, distribution and modification are not<br> +covered by this License; they are outside its scope. The act of<br> +running the Program is not restricted, and the output from the Program<br> +is covered only if its contents constitute a work based on the<br> +Program (independent of having been made by running the Program).<br> +Whether that is true depends on what the Program does.<br> +<br> + 1. You may copy and distribute verbatim copies of the Program's<br> +source code as you receive it, in any medium, provided that you<br> +conspicuously and appropriately publish on each copy an appropriate<br> +copyright notice and disclaimer of warranty; keep intact all the<br> +notices that refer to this License and to the absence of any warranty;<br> +and give any other recipients of the Program a copy of this License<br> +along with the Program.<br> +<br> +You may charge a fee for the physical act of transferring a copy, and<br> +you may at your option offer warranty protection in exchange for a fee.<br> +<br> + 2. You may modify your copy or copies of the Program or any portion<br> +of it, thus forming a work based on the Program, and copy and<br> +distribute such modifications or work under the terms of Section 1<br> +above, provided that you also meet all of these conditions:<br> +<br> + a) You must cause the modified files to carry prominent notices<br> + stating that you changed the files and the date of any change.<br> +<br> + b) You must cause any work that you distribute or publish, that in<br> + whole or in part contains or is derived from the Program or any<br> + part thereof, to be licensed as a whole at no charge to all third<br> + parties under the terms of this License.<br> +<br> + c) If the modified program normally reads commands interactively<br> + when run, you must cause it, when started running for such<br> + interactive use in the most ordinary way, to print or display an<br> + announcement including an appropriate copyright notice and a<br> + notice that there is no warranty (or else, saying that you provide<br> + a warranty) and that users may redistribute the program under<br> + these conditions, and telling the user how to view a copy of this<br> + License. (Exception: if the Program itself is interactive but<br> + does not normally print such an announcement, your work based on<br> + the Program is not required to print an announcement.)<br> +<br> +These requirements apply to the modified work as a whole. If<br> +identifiable sections of that work are not derived from the Program,<br> +and can be reasonably considered independent and separate works in<br> +themselves, then this License, and its terms, do not apply to those<br> +sections when you distribute them as separate works. But when you<br> +distribute the same sections as part of a whole which is a work based<br> +on the Program, the distribution of the whole must be on the terms of<br> +this License, whose permissions for other licensees extend to the<br> +entire whole, and thus to each and every part regardless of who wrote it.<br> +<br> +Thus, it is not the intent of this section to claim rights or contest<br> +your rights to work written entirely by you; rather, the intent is to<br> +exercise the right to control the distribution of derivative or<br> +collective works based on the Program.<br> +<br> +In addition, mere aggregation of another work not based on the Program<br> +with the Program (or with a work based on the Program) on a volume of<br> +a storage or distribution medium does not bring the other work under<br> +the scope of this License.<br> +<br> + 3. You may copy and distribute the Program (or a work based on it,<br> +under Section 2) in object code or executable form under the terms of<br> +Sections 1 and 2 above provided that you also do one of the following:<br> +<br> + a) Accompany it with the complete corresponding machine-readable<br> + source code, which must be distributed under the terms of Sections<br> + 1 and 2 above on a medium customarily used for software interchange; or,<br> +<br> + b) Accompany it with a written offer, valid for at least three<br> + years, to give any third party, for a charge no more than your<br> + cost of physically performing source distribution, a complete<br> + machine-readable copy of the corresponding source code, to be<br> + distributed under the terms of Sections 1 and 2 above on a medium<br> + customarily used for software interchange; or,<br> +<br> + c) Accompany it with the information you received as to the offer<br> + to distribute corresponding source code. (This alternative is<br> + allowed only for noncommercial distribution and only if you<br> + received the program in object code or executable form with such<br> + an offer, in accord with Subsection b above.)<br> +<br> +The source code for a work means the preferred form of the work for<br> +making modifications to it. For an executable work, complete source<br> +code means all the source code for all modules it contains, plus any<br> +associated interface definition files, plus the scripts used to<br> +control compilation and installation of the executable. However, as a<br> +special exception, the source code distributed need not include<br> +anything that is normally distributed (in either source or binary<br> +form) with the major components (compiler, kernel, and so on) of the<br> +operating system on which the executable runs, unless that component<br> +itself accompanies the executable.<br> +<br> +If distribution of executable or object code is made by offering<br> +access to copy from a designated place, then offering equivalent<br> +access to copy the source code from the same place counts as<br> +distribution of the source code, even though third parties are not<br> +compelled to copy the source along with the object code.<br> +<br> + 4. You may not copy, modify, sublicense, or distribute the Program<br> +except as expressly provided under this License. Any attempt<br> +otherwise to copy, modify, sublicense or distribute the Program is<br> +void, and will automatically terminate your rights under this License.<br> +However, parties who have received copies, or rights, from you under<br> +this License will not have their licenses terminated so long as such<br> +parties remain in full compliance.<br> +<br> + 5. You are not required to accept this License, since you have not<br> +signed it. However, nothing else grants you permission to modify or<br> +distribute the Program or its derivative works. These actions are<br> +prohibited by law if you do not accept this License. Therefore, by<br> +modifying or distributing the Program (or any work based on the<br> +Program), you indicate your acceptance of this License to do so, and<br> +all its terms and conditions for copying, distributing or modifying<br> +the Program or works based on it.<br> +<br> + 6. Each time you redistribute the Program (or any work based on the<br> +Program), the recipient automatically receives a license from the<br> +original licensor to copy, distribute or modify the Program subject to<br> +these terms and conditions. You may not impose any further<br> +restrictions on the recipients' exercise of the rights granted herein.<br> +You are not responsible for enforcing compliance by third parties to<br> +this License.<br> +<br> + 7. If, as a consequence of a court judgment or allegation of patent<br> +infringement or for any other reason (not limited to patent issues),<br> +conditions are imposed on you (whether by court order, agreement or<br> +otherwise) that contradict the conditions of this License, they do not<br> +excuse you from the conditions of this License. If you cannot<br> +distribute so as to satisfy simultaneously your obligations under this<br> +License and any other pertinent obligations, then as a consequence you<br> +may not distribute the Program at all. For example, if a patent<br> +license would not permit royalty-free redistribution of the Program by<br> +all those who receive copies directly or indirectly through you, then<br> +the only way you could satisfy both it and this License would be to<br> +refrain entirely from distribution of the Program.<br> +<br> +If any portion of this section is held invalid or unenforceable under<br> +any particular circumstance, the balance of the section is intended to<br> +apply and the section as a whole is intended to apply in other<br> +circumstances.<br> +<br> +It is not the purpose of this section to induce you to infringe any<br> +patents or other property right claims or to contest validity of any<br> +such claims; this section has the sole purpose of protecting the<br> +integrity of the free software distribution system, which is<br> +implemented by public license practices. Many people have made<br> +generous contributions to the wide range of software distributed<br> +through that system in reliance on consistent application of that<br> +system; it is up to the author/donor to decide if he or she is willing<br> +to distribute software through any other system and a licensee cannot<br> +impose that choice.<br> +<br> +This section is intended to make thoroughly clear what is believed to<br> +be a consequence of the rest of this License.<br> +<br> + 8. If the distribution and/or use of the Program is restricted in<br> +certain countries either by patents or by copyrighted interfaces, the<br> +original copyright holder who places the Program under this License<br> +may add an explicit geographical distribution limitation excluding<br> +those countries, so that distribution is permitted only in or among<br> +countries not thus excluded. In such case, this License incorporates<br> +the limitation as if written in the body of this License.<br> +<br> + 9. The Free Software Foundation may publish revised and/or new versions<br> +of the General Public License from time to time. Such new versions will<br> +be similar in spirit to the present version, but may differ in detail to<br> +address new problems or concerns.<br> +<br> +Each version is given a distinguishing version number. If the Program<br> +specifies a version number of this License which applies to it and "any<br> +later version", you have the option of following the terms and conditions<br> +either of that version or of any later version published by the Free<br> +Software Foundation. If the Program does not specify a version number of<br> +this License, you may choose any version ever published by the Free Software<br> +Foundation.<br> +<br> + 10. If you wish to incorporate parts of the Program into other free<br> +programs whose distribution conditions are different, write to the author<br> +to ask for permission. For software which is copyrighted by the Free<br> +Software Foundation, write to the Free Software Foundation; we sometimes<br> +make exceptions for this. Our decision will be guided by the two goals<br> +of preserving the free status of all derivatives of our free software and<br> +of promoting the sharing and reuse of software generally.<br> +<br> + NO WARRANTY<br> +<br> + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY<br> +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN<br> +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES<br> +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED<br> +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF<br> +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS<br> +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE<br> +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,<br> +REPAIR OR CORRECTION.<br> +<br> + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING<br> +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR<br> +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,<br> +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING<br> +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED<br> +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY<br> +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER<br> +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE<br> +POSSIBILITY OF SUCH DAMAGES.<br> +<br> + END OF TERMS AND CONDITIONS<br> +<br> + How to Apply These Terms to Your New Programs<br> +<br> + If you develop a new program, and you want it to be of the greatest<br> +possible use to the public, the best way to achieve this is to make it<br> +free software which everyone can redistribute and change under these terms.<br> +<br> + To do so, attach the following notices to the program. It is safest<br> +to attach them to the start of each source file to most effectively<br> +convey the exclusion of warranty; and each file should have at least<br> +the "copyright" line and a pointer to where the full notice is found.<br> +<br> + <one line to give the program's name and a brief idea of what it does.><br> + Copyright (C) <year> <name of author><br> +<br> + This program is free software; you can redistribute it and/or modify<br> + it under the terms of the GNU General Public License as published by<br> + the Free Software Foundation; either version 2 of the License, or<br> + (at your option) any later version.<br> +<br> + This program is distributed in the hope that it will be useful,<br> + but WITHOUT ANY WARRANTY; without even the implied warranty of<br> + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the<br> + GNU General Public License for more details.<br> +<br> + You should have received a copy of the GNU General Public License along<br> + with this program; if not, write to the Free Software Foundation, Inc.,<br> + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.<br> +<br> +Also add information on how to contact you by electronic and paper mail.<br> +<br> +If the program is interactive, make it output a short notice like this<br> +when it starts in an interactive mode:<br> +<br> + Gnomovision version 69, Copyright (C) year name of author<br> + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.<br> + This is free software, and you are welcome to redistribute it<br> + under certain conditions; type `show c' for details.<br> +<br> +The hypothetical commands `show w' and `show c' should show the appropriate<br> +parts of the General Public License. Of course, the commands you use may<br> +be called something other than `show w' and `show c'; they could even be<br> +mouse-clicks or menu items--whatever suits your program.<br> +<br> +You should also get your employer (if you work as a programmer) or your<br> +school, if any, to sign a "copyright disclaimer" for the program, if<br> +necessary. Here is a sample; alter the names:<br> +<br> + Yoyodyne, Inc., hereby disclaims all copyright interest in the program<br> + `Gnomovision' (which makes passes at compilers) written by James Hacker.<br> +<br> + <signature of Ty Coon>, 1 April 1989<br> + Ty Coon, President of Vice<br> +<br> +This General Public License does not permit incorporating your program into<br> +proprietary programs. If your program is a subroutine library, you may<br> +consider it more useful to permit linking proprietary applications with the<br> +library. If this is what you want to do, use the GNU Lesser General<br> +Public License instead of this License.<br> +</body> +</html> diff --git a/doc/License-gpl-2.rtf b/doc/License-gpl-2.rtf new file mode 100644 index 00000000..aef99d38 --- /dev/null +++ b/doc/License-gpl-2.rtf @@ -0,0 +1,356 @@ +{\rtf1\ansi\deff1\adeflang1025
+{\fonttbl{\f0\froman\fprq2\fcharset128 Times New Roman;}{\f1\froman\fprq2\fcharset0 Times New Roman;}{\f2\fswiss\fprq2\fcharset0 Bitstream Vera Sans;}{\f3\fnil\fprq0\fcharset128 Palatino Linotype;}{\f4\froman\fprq2\fcharset0 Times New Roman;}{\f5\fswiss\fprq2\fcharset0 Arial;}{\f6\fmodern\fprq1\fcharset0 Bitstream Vera Sans Mono;}{\f7\fmodern\fprq1\fcharset0 Bitstream Vera Sans;}}
+{\colortbl;\red0\green0\blue0;\red128\green128\blue128;}
+{\stylesheet{\s1\rtlch\afs24\lang1081\ltrch\dbch\af2\langfe2052\hich\fs24\lang1031\loch\fs24\lang1031\snext1 Normal;}
+{\s2\sb240\sa120\keepn\rtlch\af5\afs28\lang1081\ltrch\dbch\af1\langfe2052\hich\f5\fs28\lang1031\loch\f5\fs28\lang1031\sbasedon1\snext3 Heading;}
+{\s3\sa120\rtlch\afs24\lang1081\ltrch\dbch\af2\langfe2052\hich\fs24\lang1031\loch\fs24\lang1031\sbasedon1\snext3 Body Text;}
+{\s4\sa120\rtlch\afs24\lang1081\ltrch\dbch\af2\langfe2052\hich\fs24\lang1031\loch\fs24\lang1031\sbasedon3\snext4 List;}
+{\s5\sb120\sa120\rtlch\afs24\lang1081\ai\ltrch\dbch\af2\langfe2052\hich\f3\fs24\lang1031\i\loch\f3\fs24\lang1031\i\sbasedon1\snext5 caption;}
+{\s6\rtlch\afs24\lang1081\ltrch\dbch\af2\langfe2052\hich\fs24\lang1031\loch\fs24\lang1031\sbasedon1\snext6 Index;}
+{\s7\sb120\sa120\rtlch\afs24\lang1081\ai\ltrch\dbch\af2\langfe2052\hich\fs24\lang1031\i\loch\fs24\lang1031\i\sbasedon1\snext7 caption;}
+{\s8\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031\sbasedon1\snext8 Preformatted Text;}
+}
+{\info{\creatim\yr0\mo0\dy0\hr0\min0}{\revtim\yr0\mo0\dy0\hr0\min0}{\printim\yr0\mo0\dy0\hr0\min0}{\comment StarWriter}{\vern3200}}\deftab709
+{\*\pgdsctbl
+{\pgdsc0\pgdscuse195\pgwsxn11906\pghsxn16838\marglsxn1134\margrsxn1134\margtsxn1134\margbsxn1134\pgdscnxt0 Standard;}}
+{\*\pgdscno0}\paperh16838\paperw11906\margl1134\margr1134\margt1134\margb1134\sectd\sbknone\pgwsxn11906\pghsxn16838\marglsxn1134\margrsxn1134\margtsxn1134\margbsxn1134\ftnbj\ftnstart1\ftnrstcont\ftnnar\aenddoc\aftnrstcont\aftnstart1\aftnnrlc
+\pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 GNU GENERAL PUBLIC LICENSE}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Version 2, June 1991}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Copyright (C) 1989, 1991 Free Software Foundation, Inc.,}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Everyone is permitted to copy and distribute verbatim copies}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 of this license document, but changing it is not allowed.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Preamble}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 The licenses for most software are designed to take away your}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 freedom to share and change it. By contrast, the GNU General Public}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 License is intended to guarantee your freedom to share and change free}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 software--to make sure the software is free for all its users. This}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 General Public License applies to most of the Free Software}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Foundation's software and to any other program whose authors commit to}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 using it. (Some other Free Software Foundation software is covered by}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 the GNU Lesser General Public License instead.) You can apply it to}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 your programs, too.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 When we speak of free software, we are referring to freedom, not}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 price. Our General Public Licenses are designed to make sure that you}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 have the freedom to distribute copies of free software (and charge for}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 this service if you wish), that you receive source code or can get it}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 if you want it, that you can change the software or use pieces of it}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 in new free programs; and that you know you can do these things.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 To protect your rights, we need to make restrictions that forbid}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 anyone to deny you these rights or to ask you to surrender the rights.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 These restrictions translate to certain responsibilities for you if you}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 distribute copies of the software, or if you modify it.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 For example, if you distribute copies of such a program, whether}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 gratis or for a fee, you must give the recipients all the rights that}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 you have. You must make sure that they, too, receive or can get the}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 source code. And you must show them these terms so they know their}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 rights.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 We protect your rights with two steps: (1) copyright the software, and}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 (2) offer you this license which gives you legal permission to copy,}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 distribute and/or modify the software.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Also, for each author's protection and ours, we want to make certain}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 that everyone understands that there is no warranty for this free}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 software. If the software is modified by someone else and passed on, we}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 want its recipients to know that what they have is not the original, so}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 that any problems introduced by others will not reflect on the original}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 authors' reputations.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Finally, any free program is threatened constantly by software}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 patents. We wish to avoid the danger that redistributors of a free}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 program will individually obtain patent licenses, in effect making the}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 program proprietary. To prevent this, we have made it clear that any}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 patent must be licensed for everyone's free use or not licensed at all.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 The precise terms and conditions for copying, distribution and}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 modification follow.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 GNU GENERAL PUBLIC LICENSE}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 0. This License applies to any program or other work which contains}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 a notice placed by the copyright holder saying it may be distributed}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 under the terms of this General Public License. The "Program", below,}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 refers to any such program or work, and a "work based on the Program"}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 means either the Program or any derivative work under copyright law:}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 that is to say, a work containing the Program or a portion of it,}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 either verbatim or with modifications and/or translated into another}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 language. (Hereinafter, translation is included without limitation in}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 the term "modification".) Each licensee is addressed as "you".}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Activities other than copying, distribution and modification are not}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 covered by this License; they are outside its scope. The act of}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 running the Program is not restricted, and the output from the Program}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 is covered only if its contents constitute a work based on the}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Program (independent of having been made by running the Program).}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Whether that is true depends on what the Program does.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 1. You may copy and distribute verbatim copies of the Program's}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 source code as you receive it, in any medium, provided that you}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 conspicuously and appropriately publish on each copy an appropriate}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 copyright notice and disclaimer of warranty; keep intact all the}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 notices that refer to this License and to the absence of any warranty;}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 and give any other recipients of the Program a copy of this License}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 along with the Program.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 You may charge a fee for the physical act of transferring a copy, and}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 you may at your option offer warranty protection in exchange for a fee.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 2. You may modify your copy or copies of the Program or any portion}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 of it, thus forming a work based on the Program, and copy and}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 distribute such modifications or work under the terms of Section 1}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 above, provided that you also meet all of these conditions:}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 a) You must cause the modified files to carry prominent notices}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 stating that you changed the files and the date of any change.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 b) You must cause any work that you distribute or publish, that in}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 whole or in part contains or is derived from the Program or any}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 part thereof, to be licensed as a whole at no charge to all third}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 parties under the terms of this License.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 c) If the modified program normally reads commands interactively}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 when run, you must cause it, when started running for such}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 interactive use in the most ordinary way, to print or display an}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 announcement including an appropriate copyright notice and a}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 notice that there is no warranty (or else, saying that you provide}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 a warranty) and that users may redistribute the program under}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 these conditions, and telling the user how to view a copy of this}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 License. (Exception: if the Program itself is interactive but}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 does not normally print such an announcement, your work based on}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 the Program is not required to print an announcement.)}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 These requirements apply to the modified work as a whole. If}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 identifiable sections of that work are not derived from the Program,}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 and can be reasonably considered independent and separate works in}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 themselves, then this License, and its terms, do not apply to those}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 sections when you distribute them as separate works. But when you}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 distribute the same sections as part of a whole which is a work based}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 on the Program, the distribution of the whole must be on the terms of}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 this License, whose permissions for other licensees extend to the}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 entire whole, and thus to each and every part regardless of who wrote it.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Thus, it is not the intent of this section to claim rights or contest}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 your rights to work written entirely by you; rather, the intent is to}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 exercise the right to control the distribution of derivative or}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 collective works based on the Program.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 In addition, mere aggregation of another work not based on the Program}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 with the Program (or with a work based on the Program) on a volume of}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 a storage or distribution medium does not bring the other work under}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 the scope of this License.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 3. You may copy and distribute the Program (or a work based on it,}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 under Section 2) in object code or executable form under the terms of}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Sections 1 and 2 above provided that you also do one of the following:}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 a) Accompany it with the complete corresponding machine-readable}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 source code, which must be distributed under the terms of Sections}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 1 and 2 above on a medium customarily used for software interchange; or,}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 b) Accompany it with a written offer, valid for at least three}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 years, to give any third party, for a charge no more than your}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 cost of physically performing source distribution, a complete}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 machine-readable copy of the corresponding source code, to be}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 distributed under the terms of Sections 1 and 2 above on a medium}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 customarily used for software interchange; or,}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 c) Accompany it with the information you received as to the offer}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 to distribute corresponding source code. (This alternative is}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 allowed only for noncommercial distribution and only if you}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 received the program in object code or executable form with such}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 an offer, in accord with Subsection b above.)}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 The source code for a work means the preferred form of the work for}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 making modifications to it. For an executable work, complete source}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 code means all the source code for all modules it contains, plus any}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 associated interface definition files, plus the scripts used to}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 control compilation and installation of the executable. However, as a}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 special exception, the source code distributed need not include}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 anything that is normally distributed (in either source or binary}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 form) with the major components (compiler, kernel, and so on) of the}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 operating system on which the executable runs, unless that component}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 itself accompanies the executable.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 If distribution of executable or object code is made by offering}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 access to copy from a designated place, then offering equivalent}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 access to copy the source code from the same place counts as}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 distribution of the source code, even though third parties are not}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 compelled to copy the source along with the object code.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 4. You may not copy, modify, sublicense, or distribute the Program}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 except as expressly provided under this License. Any attempt}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 otherwise to copy, modify, sublicense or distribute the Program is}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 void, and will automatically terminate your rights under this License.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 However, parties who have received copies, or rights, from you under}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 this License will not have their licenses terminated so long as such}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 parties remain in full compliance.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 5. You are not required to accept this License, since you have not}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 signed it. However, nothing else grants you permission to modify or}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 distribute the Program or its derivative works. These actions are}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 prohibited by law if you do not accept this License. Therefore, by}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 modifying or distributing the Program (or any work based on the}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Program), you indicate your acceptance of this License to do so, and}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 all its terms and conditions for copying, distributing or modifying}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 the Program or works based on it.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 6. Each time you redistribute the Program (or any work based on the}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Program), the recipient automatically receives a license from the}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 original licensor to copy, distribute or modify the Program subject to}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 these terms and conditions. You may not impose any further}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 restrictions on the recipients' exercise of the rights granted herein.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 You are not responsible for enforcing compliance by third parties to}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 this License.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 7. If, as a consequence of a court judgment or allegation of patent}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 infringement or for any other reason (not limited to patent issues),}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 conditions are imposed on you (whether by court order, agreement or}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 otherwise) that contradict the conditions of this License, they do not}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 excuse you from the conditions of this License. If you cannot}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 distribute so as to satisfy simultaneously your obligations under this}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 License and any other pertinent obligations, then as a consequence you}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 may not distribute the Program at all. For example, if a patent}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 license would not permit royalty-free redistribution of the Program by}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 all those who receive copies directly or indirectly through you, then}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 the only way you could satisfy both it and this License would be to}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 refrain entirely from distribution of the Program.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 If any portion of this section is held invalid or unenforceable under}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 any particular circumstance, the balance of the section is intended to}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 apply and the section as a whole is intended to apply in other}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 circumstances.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 It is not the purpose of this section to induce you to infringe any}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 patents or other property right claims or to contest validity of any}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 such claims; this section has the sole purpose of protecting the}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 integrity of the free software distribution system, which is}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 implemented by public license practices. Many people have made}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 generous contributions to the wide range of software distributed}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 through that system in reliance on consistent application of that}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 system; it is up to the author/donor to decide if he or she is willing}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 to distribute software through any other system and a licensee cannot}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 impose that choice.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 This section is intended to make thoroughly clear what is believed to}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 be a consequence of the rest of this License.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 8. If the distribution and/or use of the Program is restricted in}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 certain countries either by patents or by copyrighted interfaces, the}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 original copyright holder who places the Program under this License}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 may add an explicit geographical distribution limitation excluding}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 those countries, so that distribution is permitted only in or among}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 countries not thus excluded. In such case, this License incorporates}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 the limitation as if written in the body of this License.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 9. The Free Software Foundation may publish revised and/or new versions}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 of the General Public License from time to time. Such new versions will}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 be similar in spirit to the present version, but may differ in detail to}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 address new problems or concerns.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Each version is given a distinguishing version number. If the Program}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 specifies a version number of this License which applies to it and "any}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 later version", you have the option of following the terms and conditions}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 either of that version or of any later version published by the Free}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Software Foundation. If the Program does not specify a version number of}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 this License, you may choose any version ever published by the Free Software}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Foundation.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 10. If you wish to incorporate parts of the Program into other free}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 programs whose distribution conditions are different, write to the author}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 to ask for permission. For software which is copyrighted by the Free}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Software Foundation, write to the Free Software Foundation; we sometimes}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 make exceptions for this. Our decision will be guided by the two goals}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 of preserving the free status of all derivatives of our free software and}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 of promoting the sharing and reuse of software generally.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 NO WARRANTY}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 REPAIR OR CORRECTION.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 POSSIBILITY OF SUCH DAMAGES.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 END OF TERMS AND CONDITIONS}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 How to Apply These Terms to Your New Programs}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 If you develop a new program, and you want it to be of the greatest}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 possible use to the public, the best way to achieve this is to make it}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 free software which everyone can redistribute and change under these terms.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 To do so, attach the following notices to the program. It is safest}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 to attach them to the start of each source file to most effectively}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 convey the exclusion of warranty; and each file should have at least}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 the "copyright" line and a pointer to where the full notice is found.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 <one line to give the program's name and a brief idea of what it does.>}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Copyright (C) <year> <name of author>}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 This program is free software; you can redistribute it and/or modify}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 it under the terms of the GNU General Public License as published by}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 the Free Software Foundation; either version 2 of the License, or}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 (at your option) any later version.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 This program is distributed in the hope that it will be useful,}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 but WITHOUT ANY WARRANTY; without even the implied warranty of}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 GNU General Public License for more details.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 You should have received a copy of the GNU General Public License along}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 with this program; if not, write to the Free Software Foundation, Inc.,}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Also add information on how to contact you by electronic and paper mail.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 If the program is interactive, make it output a short notice like this}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 when it starts in an interactive mode:}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Gnomovision version 69, Copyright (C) year name of author}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 This is free software, and you are welcome to redistribute it}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 under certain conditions; type `show c' for details.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 The hypothetical commands `show w' and `show c' should show the appropriate}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 parts of the General Public License. Of course, the commands you use may}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 be called something other than `show w' and `show c'; they could even be}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 mouse-clicks or menu items--whatever suits your program.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 You should also get your employer (if you work as a programmer) or your}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 school, if any, to sign a "copyright disclaimer" for the program, if}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 necessary. Here is a sample; alter the names:}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Yoyodyne, Inc., hereby disclaims all copyright interest in the program}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 `Gnomovision' (which makes passes at compilers) written by James Hacker.}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 <signature of Ty Coon>, 1 April 1989}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch }{\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Ty Coon, President of Vice}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 This General Public License does not permit incorporating your program into}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 proprietary programs. If your program is a subroutine library, you may}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 consider it more useful to permit linking proprietary applications with the}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 library. If this is what you want to do, use the GNU Lesser General}
+\par \pard\plain \ltrpar\s8\ql\rtlch\af6\afs20\lang1081\ltrch\dbch\af7\langfe2052\hich\f6\fs20\lang1031\loch\f6\fs20\lang1031 {\rtlch \ltrch\loch\f6\fs20\lang1031\i0\b0 Public License instead of this License.}
+\par }
diff --git a/doc/License-gpl-2.txt b/doc/License-gpl-2.txt new file mode 100644 index 00000000..d511905c --- /dev/null +++ b/doc/License-gpl-2.txt @@ -0,0 +1,339 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Lesser General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + <one line to give the program's name and a brief idea of what it does.> + Copyright (C) <year> <name of author> + + 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., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + <signature of Ty Coon>, 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. diff --git a/doc/License-gpl-3.0.html b/doc/License-gpl-3.0.html new file mode 100644 index 00000000..f824a620 --- /dev/null +++ b/doc/License-gpl-3.0.html @@ -0,0 +1,771 @@ +<!DOCTYPE html> +<html> + +<head> + <meta charset="UTF-8"/> + <style> + body { font-family: Verdana, Arial, Helvetica, sans-serif; } + </style> +</head> + +<body lang=EN-US style='word-wrap:break-word'> + +<p>COPYING file for VirtualBox versions 7.0 and later versions +that include this file</p> + +<p>Preliminary notes:</p> + +<p style='text-align:justify'>1) The majority of the code in +the VirtualBox base package is licensed under the GNU General Public License, +version 3 (GPL). VirtualBox contains many components developed by Oracle and +various third parties. The license for each component is located in the +licensing documentation and/or in the component's source code.</p> + +<p style='text-align:justify'>2) As an exception to the reciprocal +license obligations of the GPL listed below, you may use any VirtualBox header +file that is marked by Oracle as licensed under both the GPL and the Common +Development and Distribution License version 1.0 (CDDL) to invoke the +unmodified VirtualBox libraries. In other words, calling such a multi-licensed +interface by dynamically linking to the unmodified VirtualBox libraries is +considered a normal use of VirtualBox and does not turn the calling code into a +derived work of VirtualBox. In particular, this applies to code that wants to +extend VirtualBox by way of the Extension Pack mechanism declared in the +ExtPack.h header file.</p> + +<p style='text-align:justify'>3) Whoever creates or distributes +a derived work based on VirtualBox is not obligated to grant the above +exceptions for such a version. The GPL permits you to release a modified +version without the above exception; in addition, Oracle hereby also allows you +to release a modified version which carries forward these exceptions.</p> + +<p>Oracle America, Inc.</p> + +<p>---</p> + +<p>GNU GENERAL PUBLIC LICENSE</p> + +<p>Version 3, 29 June 2007</p> + +<p>Copyright © 2007 Free Software Foundation, Inc. +<https://fsf.org/></p> + +<p style='text-align:justify'>Everyone is permitted to copy and +distribute verbatim copies of this license document, but changing it is not +allowed.</p> + +<p>Preamble</p> + +<p>The GNU General Public License is a free, copyleft license +for software and other kinds of works.</p> + +<p style='text-align:justify'>The licenses for most software +and other practical works are designed to take away your freedom to share and +change the works. By contrast, the GNU General Public License is intended to +guarantee your freedom to share and change all versions of a program--to make +sure it remains free software for all its users. We, the Free Software +Foundation, use the GNU General Public License for most of our software; it +applies also to any other work released this way by its authors. You can apply +it to your programs, too.</p> + +<p style='text-align:justify'>When we speak of free software, +we are referring to freedom, not price. Our General Public Licenses are +designed to make sure that you have the freedom to distribute copies of free +software (and charge for them if you wish), that you receive source code or can +get it if you want it, that you can change the software or use pieces of it in +new free programs, and that you know you can do these things.</p> + +<p style='text-align:justify'>To protect your rights, we need +to prevent others from denying you these rights or asking you to surrender the +rights. Therefore, you have certain responsibilities if you distribute copies +of the software, or if you modify it: responsibilities to respect the freedom +of others.</p> + +<p style='text-align:justify'>For example, if you distribute +copies of such a program, whether gratis or for a fee, you must pass on to the +recipients the same freedoms that you received. You must make sure that they, +too, receive or can get the source code. And you must show them these terms so +they know their rights.</p> + +<p style='text-align:justify'>Developers that use the GNU GPL +protect your rights with two steps: (1) assert copyright on the software, and +(2) offer you this License giving you legal permission to copy, distribute +and/or modify it.</p> + +<p style='text-align:justify'>For the developers' and authors' +protection, the GPL clearly explains that there is no warranty for this free +software. For both users' and authors' sake, the GPL requires that modified +versions be marked as changed, so that their problems will not be attributed +erroneously to authors of previous versions.</p> + +<p style='text-align:justify'>Some devices are designed to deny +users access to install or run modified versions of the software inside them, +although the manufacturer can do so. This is fundamentally incompatible with +the aim of protecting users' freedom to change the software. The systematic +pattern of such abuse occurs in the area of products for individuals to use, +which is precisely where it is most unacceptable. Therefore, we have designed +this version of the GPL to prohibit the practice for those products. If such +problems arise substantially in other domains, we stand ready to extend this +provision to those domains in future versions of the GPL, as needed to protect +the freedom of users.</p> + +<p style='text-align:justify'>Finally, every program is +threatened constantly by software patents. States should not allow patents to +restrict development and use of software on general-purpose computers, but in +those that do, we wish to avoid the special danger that patents applied to a +free program could make it effectively proprietary. To prevent this, the GPL +assures that patents cannot be used to render the program non-free.</p> + +<p style='text-align:justify'>The precise terms and conditions +for copying, distribution and modification follow.</p> + +<p style='text-align:justify'>TERMS AND CONDITIONS</p> + +<p style='text-align:justify'>0. Definitions.</p> + +<p style='text-align:justify'>“This License” refers to version +3 of the GNU General Public License.</p> + +<p style='text-align:justify'>“Copyright” also means +copyright-like laws that apply to other kinds of works, such as semiconductor +masks.</p> + +<p style='text-align:justify'>“The Program” refers to any +copyrightable work licensed under this License. Each licensee is addressed as +“you”. “Licensees” and “recipients” may be individuals or organizations.</p> + +<p style='text-align:justify'>To “modify” a work means to copy +from or adapt all or part of the work in a fashion requiring copyright +permission, other than the making of an exact copy. The resulting work is +called a “modified version” of the earlier work or a work “based on” the +earlier work.</p> + +<p style='text-align:justify'>A “covered work” means either the +unmodified Program or a work based on the Program.</p> + +<p style='text-align:justify'>To “propagate” a work means to do +anything with it that, without permission, would make you directly or +secondarily liable for infringement under applicable copyright law, except +executing it on a computer or modifying a private copy. Propagation includes +copying, distribution (with or without modification), making available to the +public, and in some countries other activities as well.</p> + +<p style='text-align:justify'>To “convey” a work means any kind +of propagation that enables other parties to make or receive copies. Mere +interaction with a user through a computer network, with no transfer of a copy, +is not conveying.</p> + +<p style='text-align:justify'>An interactive user interface +displays “Appropriate Legal Notices” to the extent that it includes a +convenient and prominently visible feature that (1) displays an appropriate +copyright notice, and (2) tells the user that there is no warranty for the work +(except to the extent that warranties are provided), that licensees may convey +the work under this License, and how to view a copy of this License. If the +interface presents a list of user commands or options, such as a menu, a +prominent item in the list meets this criterion.</p> + +<p style='text-align:justify'>1. Source Code.</p> + +<p style='text-align:justify'>The “source code” for a work +means the preferred form of the work for making modifications to it. “Object +code” means any non-source form of a work.</p> + +<p style='text-align:justify'>A “Standard Interface” means an +interface that either is an official standard defined by a recognized standards +body, or, in the case of interfaces specified for a particular programming +language, one that is widely used among developers working in that language.</p> + +<p style='text-align:justify'>The “System Libraries” of an +executable work include anything, other than the work as a whole, that (a) is +included in the normal form of packaging a Major Component, but which is not +part of that Major Component, and (b) serves only to enable use of the work +with that Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A “Major +Component”, in this context, means a major essential component (kernel, window +system, and so on) of the specific operating system (if any) on which the +executable work runs, or a compiler used to produce the work, or an object code +interpreter used to run it.</p> + +<p style='text-align:justify'>The “Corresponding Source” for a +work in object code form means all the source code needed to generate, install, +and (for an executable work) run the object code and to modify the work, +including scripts to control those activities. However, it does not include the +work's System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but which are +not part of the work. For example, Corresponding Source includes interface +definition files associated with source files for the work, and the source code +for shared libraries and dynamically linked subprograms that the work is +specifically designed to require, such as by intimate data communication or +control flow between those subprograms and other parts of the work.</p> + +<p style='text-align:justify'>The Corresponding Source need not +include anything that users can regenerate automatically from other parts of +the Corresponding Source.</p> + +<p style='text-align:justify'>The Corresponding Source for a +work in source code form is that same work.</p> + +<p style='text-align:justify'>2. Basic Permissions.</p> + +<p style='text-align:justify'>All rights granted under this +License are granted for the term of copyright on the Program, and are irrevocable +provided the stated conditions are met. This License explicitly affirms your +unlimited permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its content, +constitutes a covered work. This License acknowledges your rights of fair use +or other equivalent, as provided by copyright law.</p> + +<p style='text-align:justify'>You may make, run and propagate +covered works that you do not convey, without conditions so long as your +license otherwise remains in force. You may convey covered works to others for +the sole purpose of having them make modifications exclusively for you, or +provide you with facilities for running those works, provided that you comply +with the terms of this License in conveying all material for which you do not +control copyright. Those thus making or running the covered works for you must +do so exclusively on your behalf, under your direction and control, on terms +that prohibit them from making any copies of your copyrighted material outside +their relationship with you.</p> + +<p style='text-align:justify'>Conveying under any other +circumstances is permitted solely under the conditions stated below. +Sublicensing is not allowed; section 10 makes it unnecessary.</p> + +<p style='text-align:justify'>3. Protecting Users' Legal Rights +From Anti-Circumvention Law.</p> + +<p style='text-align:justify'>No covered work shall be deemed +part of an effective technological measure under any applicable law fulfilling +obligations under article 11 of the WIPO copyright treaty adopted on 20 +December 1996, or similar laws prohibiting or restricting circumvention of such +measures.</p> + +<p style='text-align:justify'>When you convey a covered work, +you waive any legal power to forbid circumvention of technological measures to +the extent such circumvention is effected by exercising rights under this +License with respect to the covered work, and you disclaim any intention to +limit operation or modification of the work as a means of enforcing, against +the work's users, your or third parties' legal rights to forbid circumvention +of technological measures.</p> + +<p style='text-align:justify'>4. Conveying Verbatim Copies.</p> + +<p style='text-align:justify'>You may convey verbatim copies of +the Program's source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate copyright +notice; keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; keep +intact all notices of the absence of any warranty; and give all recipients a +copy of this License along with the Program.</p> + +<p style='text-align:justify'>You may charge any price or no +price for each copy that you convey, and you may offer support or warranty +protection for a fee.</p> + +<p style='text-align:justify'>5. Conveying Modified Source +Versions.</p> + +<p style='text-align:justify'>You may convey a work based on +the Program, or the modifications to produce it from the Program, in the form +of source code under the terms of section 4, provided that you also meet all of +these conditions:</p> + +<p style='text-align:justify'> a) The work must carry prominent notices +stating that you modified it, and giving a relevant date.</p> + +<p style='text-align:justify'> b) The work must carry prominent notices +stating that it is released under this License and any conditions added under +section 7. This requirement modifies the requirement in section 4 to “keep +intact all notices”.</p> + +<p style='text-align:justify'> c) You must license the entire work, as a +whole, under this License to anyone who comes into possession of a copy. This +License will therefore apply, along with any applicable section 7 additional +terms, to the whole of the work, and all its parts, regardless of how they are +packaged. This License gives no permission to license the work in any other +way, but it does not invalidate such permission if you have separately received +it.</p> + +<p style='text-align:justify'> d) If the work has interactive user +interfaces, each must display Appropriate Legal Notices; however, if the +Program has interactive interfaces that do not display Appropriate Legal +Notices, your work need not make them do so.</p> + +<p style='text-align:justify'>A compilation of a covered work +with other separate and independent works, which are not by their nature +extensions of the covered work, and which are not combined with it such as to +form a larger program, in or on a volume of a storage or distribution medium, +is called an “aggregate” if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users beyond what +the individual works permit. Inclusion of a covered work in an aggregate does +not cause this License to apply to the other parts of the aggregate.</p> + +<p style='text-align:justify'>6. Conveying Non-Source Forms.</p> + +<p style='text-align:justify'>You may convey a covered work in +object code form under the terms of sections 4 and 5, provided that you also +convey the machine-readable Corresponding Source under the terms of this +License, in one of these ways:</p> + +<p style='text-align:justify'> a) Convey the object code in, or embodied +in, a physical product (including a physical distribution medium), accompanied +by the Corresponding Source fixed on a durable physical medium customarily used +for software interchange.</p> + +<p style='text-align:justify'> b) Convey the object code in, or embodied +in, a physical product (including a physical distribution medium), accompanied +by a written offer, valid for at least three years and valid for as long as you +offer spare parts or customer support for that product model, to give anyone +who possesses the object code either (1) a copy of the Corresponding Source for +all the software in the product that is covered by this License, on a durable +physical medium customarily used for software interchange, for a price no more +than your reasonable cost of physically performing this conveying of source, or +(2) access to copy the Corresponding Source from a network server at no charge.</p> + +<p style='text-align:justify'> c) Convey individual copies of the object +code with a copy of the written offer to provide the Corresponding Source. This +alternative is allowed only occasionally and noncommercially, and only if you +received the object code with such an offer, in accord with subsection 6b.</p> + +<p style='text-align:justify'> d) Convey the object code by offering +access from a designated place (gratis or for a charge), and offer equivalent +access to the Corresponding Source in the same way through the same place at no +further charge. You need not require recipients to copy the Corresponding +Source along with the object code. If the place to copy the object code is a +network server, the Corresponding Source may be on a different server (operated +by you or a third party) that supports equivalent copying facilities, provided you +maintain clear directions next to the object code saying where to find the +Corresponding Source. Regardless of what server hosts the Corresponding Source, +you remain obligated to ensure that it is available for as long as needed to +satisfy these requirements.</p> + +<p style='text-align:justify'> e) Convey the object code using +peer-to-peer transmission, provided you inform other peers where the object +code and Corresponding Source of the work are being offered to the general +public at no charge under subsection 6d.</p> + +<p style='text-align:justify'>A separable portion of the object +code, whose source code is excluded from the Corresponding Source as a System +Library, need not be included in conveying the object code work.</p> + +<p style='text-align:justify'>A “User Product” is either (1) a +“consumer product”, which means any tangible personal property which is +normally used for personal, family, or household purposes, or (2) anything +designed or sold for incorporation into a dwelling. In determining whether a +product is a consumer product, doubtful cases shall be resolved in favor of +coverage. For a particular product received by a particular user, “normally +used” refers to a typical or common use of that class of product, regardless of +the status of the particular user or of the way in which the particular user +actually uses, or expects or is expected to use, the product. A product is a +consumer product regardless of whether the product has substantial commercial, +industrial or non-consumer uses, unless such uses represent the only +significant mode of use of the product.</p> + +<p style='text-align:justify'>“Installation Information” for a +User Product means any methods, procedures, authorization keys, or other +information required to install and execute modified versions of a covered work +in that User Product from a modified version of its Corresponding Source. The +information must suffice to ensure that the continued functioning of the +modified object code is in no case prevented or interfered with solely because +modification has been made.</p> + +<p style='text-align:justify'>If you convey an object code work +under this section in, or with, or specifically for use in, a User Product, and +the conveying occurs as part of a transaction in which the right of possession +and use of the User Product is transferred to the recipient in perpetuity or +for a fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied by the +Installation Information. But this requirement does not apply if neither you +nor any third party retains the ability to install modified object code on the +User Product (for example, the work has been installed in ROM).</p> + +<p style='text-align:justify'>The requirement to provide +Installation Information does not include a requirement to continue to provide +support service, warranty, or updates for a work that has been modified or +installed by the recipient, or for the User Product in which it has been +modified or installed. Access to a network may be denied when the modification +itself materially and adversely affects the operation of the network or +violates the rules and protocols for communication across the network.</p> + +<p style='text-align:justify'>Corresponding Source conveyed, +and Installation Information provided, in accord with this section must be in a +format that is publicly documented (and with an implementation available to the +public in source code form), and must require no special password or key for +unpacking, reading or copying.</p> + +<p style='text-align:justify'>7. Additional Terms.</p> + +<p style='text-align:justify'>“Additional permissions” are +terms that supplement the terms of this License by making exceptions from one +or more of its conditions. Additional permissions that are applicable to the +entire Program shall be treated as though they were included in this License, +to the extent that they are valid under applicable law. If additional +permissions apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by this +License without regard to the additional permissions.</p> + +<p style='text-align:justify'>When you convey a copy of a +covered work, you may at your option remove any additional permissions from +that copy, or from any part of it. (Additional permissions may be written to +require their own removal in certain cases when you modify the work.) You may +place additional permissions on material, added by you to a covered work, for +which you have or can give appropriate copyright permission.</p> + +<p style='text-align:justify'>Notwithstanding any other provision +of this License, for material you add to a covered work, you may (if authorized +by the copyright holders of that material) supplement the terms of this License +with terms:</p> + +<p style='text-align:justify'> a) Disclaiming warranty or limiting +liability differently from the terms of sections 15 and 16 of this License; or</p> + +<p style='text-align:justify'> b) Requiring preservation of specified +reasonable legal notices or author attributions in that material or in the +Appropriate Legal Notices displayed by works containing it; or</p> + +<p style='text-align:justify'> c) Prohibiting misrepresentation of the +origin of that material, or requiring that modified versions of such material +be marked in reasonable ways as different from the original version; or</p> + +<p style='text-align:justify'> d) Limiting the use for publicity purposes +of names of licensors or authors of the material; or</p> + +<p style='text-align:justify'> e) Declining to grant rights under +trademark law for use of some trade names, trademarks, or service marks; or</p> + +<p style='text-align:justify'> f) Requiring indemnification of licensors +and authors of that material by anyone who conveys the material (or modified +versions of it) with contractual assumptions of liability to the recipient, for +any liability that these contractual assumptions directly impose on those +licensors and authors.</p> + +<p style='text-align:justify'>All other non-permissive +additional terms are considered “further restrictions” within the meaning of +section 10. If the Program as you received it, or any part of it, contains a +notice stating that it is governed by this License along with a term that is a +further restriction, you may remove that term. If a license document contains a +further restriction but permits relicensing or conveying under this License, +you may add to a covered work material governed by the terms of that license +document, provided that the further restriction does not survive such +relicensing or conveying.</p> + +<p style='text-align:justify'>If you add terms to a covered +work in accord with this section, you must place, in the relevant source files, +a statement of the additional terms that apply to those files, or a notice +indicating where to find the applicable terms.</p> + +<p style='text-align:justify'>Additional terms, permissive or +non-permissive, may be stated in the form of a separately written license, or +stated as exceptions; the above requirements apply either way.</p> + +<p style='text-align:justify'>8. Termination.</p> + +<p style='text-align:justify'>You may not propagate or modify a +covered work except as expressly provided under this License. Any attempt +otherwise to propagate or modify it is void, and will automatically terminate +your rights under this License (including any patent licenses granted under the +third paragraph of section 11).</p> + +<p style='text-align:justify'>However, if you cease all +violation of this License, then your license from a particular copyright holder +is reinstated (a) provisionally, unless and until the copyright holder +explicitly and finally terminates your license, and (b) permanently, if the +copyright holder fails to notify you of the violation by some reasonable means +prior to 60 days after the cessation.</p> + +<p style='text-align:justify'>Moreover, your license from a +particular copyright holder is reinstated permanently if the copyright holder +notifies you of the violation by some reasonable means, this is the first time +you have received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after your +receipt of the notice.</p> + +<p style='text-align:justify'>Termination of your rights under +this section does not terminate the licenses of parties who have received +copies or rights from you under this License. If your rights have been +terminated and not permanently reinstated, you do not qualify to receive new +licenses for the same material under section 10.</p> + +<p style='text-align:justify'>9. Acceptance Not Required for +Having Copies.</p> + +<p style='text-align:justify'>You are not required to accept +this License in order to receive or run a copy of the Program. Ancillary +propagation of a covered work occurring solely as a consequence of using +peer-to-peer transmission to receive a copy likewise does not require +acceptance. However, nothing other than this License grants you permission to +propagate or modify any covered work. These actions infringe copyright if you +do not accept this License. Therefore, by modifying or propagating a covered +work, you indicate your acceptance of this License to do so.</p> + +<p style='text-align:justify'>10. Automatic Licensing of +Downstream Recipients.</p> + +<p style='text-align:justify'>Each time you convey a covered +work, the recipient automatically receives a license from the original +licensors, to run, modify and propagate that work, subject to this License. You +are not responsible for enforcing compliance by third parties with this +License.</p> + +<p style='text-align:justify'>An “entity transaction” is a +transaction transferring control of an organization, or substantially all +assets of one, or subdividing an organization, or merging organizations. If +propagation of a covered work results from an entity transaction, each party to +that transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could give +under the previous paragraph, plus a right to possession of the Corresponding +Source of the work from the predecessor in interest, if the predecessor has it +or can get it with reasonable efforts.</p> + +<p style='text-align:justify'>You may not impose any further +restrictions on the exercise of the rights granted or affirmed under this +License. For example, you may not impose a license fee, royalty, or other +charge for exercise of rights granted under this License, and you may not +initiate litigation (including a cross-claim or counterclaim in a lawsuit) +alleging that any patent claim is infringed by making, using, selling, offering +for sale, or importing the Program or any portion of it.</p> + +<p style='text-align:justify'>11. Patents.</p> + +<p style='text-align:justify'>A “contributor” is a copyright +holder who authorizes use under this License of the Program or a work on which +the Program is based. The work thus licensed is called the contributor's +“contributor version”.</p> + +<p style='text-align:justify'>A contributor's “essential patent +claims” are all patent claims owned or controlled by the contributor, whether +already acquired or hereafter acquired, that would be infringed by some manner, +permitted by this License, of making, using, or selling its contributor +version, but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For purposes of +this definition, “control” includes the right to grant patent sublicenses in a +manner consistent with the requirements of this License.</p> + +<p style='text-align:justify'>Each contributor grants you a +non-exclusive, worldwide, royalty-free patent license under the contributor's +essential patent claims, to make, use, sell, offer for sale, import and +otherwise run, modify and propagate the contents of its contributor version.</p> + +<p style='text-align:justify'>In the following three +paragraphs, a “patent license” is any express agreement or commitment, however +denominated, not to enforce a patent (such as an express permission to practice +a patent or covenant not to sue for patent infringement). To “grant” such a +patent license to a party means to make such an agreement or commitment not to +enforce a patent against the party.</p> + +<p style='text-align:justify'>If you convey a covered work, +knowingly relying on a patent license, and the Corresponding Source of the work +is not available for anyone to copy, free of charge and under the terms of this +License, through a publicly available network server or other readily +accessible means, then you must either (1) cause the Corresponding Source to be +so available, or (2) arrange to deprive yourself of the benefit of the patent +license for this particular work, or (3) arrange, in a manner consistent with +the requirements of this License, to extend the patent license to downstream +recipients. “Knowingly relying” means you have actual knowledge that, but for +the patent license, your conveying the covered work in a country, or your recipient's +use of the covered work in a country, would infringe one or more identifiable +patents in that country that you have reason to believe are valid.</p> + +<p style='text-align:justify'>If, pursuant to or in connection +with a single transaction or arrangement, you convey, or propagate by procuring +conveyance of, a covered work, and grant a patent license to some of the +parties receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license you +grant is automatically extended to all recipients of the covered work and works +based on it.</p> + +<p style='text-align:justify'>A patent license is +“discriminatory” if it does not include within the scope of its coverage, +prohibits the exercise of, or is conditioned on the non-exercise of one or more +of the rights that are specifically granted under this License. You may not +convey a covered work if you are a party to an arrangement with a third party +that is in the business of distributing software, under which you make payment +to the third party based on the extent of your activity of conveying the work, +and under which the third party grants, to any of the parties who would receive +the covered work from you, a discriminatory patent license (a) in connection +with copies of the covered work conveyed by you (or copies made from those +copies), or (b) primarily for and in connection with specific products or +compilations that contain the covered work, unless you entered into that +arrangement, or that patent license was granted, prior to 28 March 2007.</p> + +<p style='text-align:justify'>Nothing in this License shall be +construed as excluding or limiting any implied license or other defenses to +infringement that may otherwise be available to you under applicable patent +law.</p> + +<p style='text-align:justify'>12. No Surrender of Others' +Freedom.</p> + +<p style='text-align:justify'>If conditions are imposed on you +(whether by court order, agreement or otherwise) that contradict the conditions +of this License, they do not excuse you from the conditions of this License. If +you cannot convey a covered work so as to satisfy simultaneously your +obligations under this License and any other pertinent obligations, then as a +consequence you may not convey it at all. For example, if you agree to terms +that obligate you to collect a royalty for further conveying from those to whom +you convey the Program, the only way you could satisfy both those terms and +this License would be to refrain entirely from conveying the Program.</p> + +<p style='text-align:justify'>13. Use with the GNU Affero General Public +License.</p> + +<p style='text-align:justify'>Notwithstanding any other +provision of this License, you have permission to link or combine any covered +work with a work licensed under version 3 of the GNU Affero +General Public License into a single combined work, and to convey the resulting +work. The terms of this License will continue to apply to the part which is the +covered work, but the special requirements of the GNU Affero +General Public License, section 13, concerning interaction through a network +will apply to the combination as such.</p> + +<p style='text-align:justify'>14. Revised Versions of this +License.</p> + +<p style='text-align:justify'>The Free Software Foundation may +publish revised and/or new versions of the GNU General Public License from time +to time. Such new versions will be similar in spirit to the present version, +but may differ in detail to address new problems or concerns.</p> + +<p style='text-align:justify'>Each version is given a +distinguishing version number. If the Program specifies that a certain numbered +version of the GNU General Public License “or any later version” applies to it, +you have the option of following the terms and conditions either of that +numbered version or of any later version published by the Free Software +Foundation. If the Program does not specify a version number of the GNU General +Public License, you may choose any version ever published by the Free Software +Foundation.</p> + +<p style='text-align:justify'>If the Program specifies that a +proxy can decide which future versions of the GNU General Public License can be +used, that proxy's public statement of acceptance of a version permanently +authorizes you to choose that version for the Program.</p> + +<p style='text-align:justify'>Later license versions may give +you additional or different permissions. However, no additional obligations are +imposed on any author or copyright holder as a result of your choosing to +follow a later version.</p> + +<p style='text-align:justify'>15. Disclaimer of Warranty.</p> + +<p style='text-align:justify'>THERE IS NO WARRANTY FOR THE +PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE +STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE +PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, +INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND +FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND +PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU +ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.</p> + +<p style='text-align:justify'>16. Limitation of Liability.</p> + +<p style='text-align:justify'>IN NO EVENT UNLESS REQUIRED BY +APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER +PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO +YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL +DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT +NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES +SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH +ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES.</p> + +<p style='text-align:justify'>17. Interpretation of Sections 15 +and 16.</p> + +<p style='text-align:justify'>If the disclaimer of warranty and +limitation of liability provided above cannot be given local legal effect +according to their terms, reviewing courts shall apply local law that most +closely approximates an absolute waiver of all civil liability in connection +with the Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee.</p> + +<p style='text-align:justify'>END OF TERMS AND CONDITIONS</p> + +<p style='text-align:justify'>How to Apply These Terms to Your +New Programs</p> + +<p style='text-align:justify'>If you develop a new program, and +you want it to be of the greatest possible use to the public, the best way to +achieve this is to make it free software which everyone can redistribute and +change under these terms.</p> + +<p style='text-align:justify'>To do so, attach the following +notices to the program. It is safest to attach them to the start of each source +file to most effectively state the exclusion of warranty; and each file should +have at least the “copyright” line and a pointer to where the full notice is found.</p> + +<p style='text-align:justify'> <one line to give the program's name and +a brief idea of what it does.></p> + +<p style='text-align:justify'> Copyright (C) <year> <name of author></p> + +<p style='text-align:justify'> This program is free software: you can +redistribute it and/or modify</p> + +<p style='text-align:justify'> it under the terms of the GNU General +Public License as published by</p> + +<p style='text-align:justify'> the Free Software Foundation, either +version 3 of the License, or</p> + +<p style='text-align:justify'> (at your option) +any later version.</p> + +<p style='text-align:justify'> This program is distributed in the hope +that it will be useful,</p> + +<p style='text-align:justify'> but WITHOUT ANY WARRANTY; without even the +implied warranty of</p> + +<p style='text-align:justify'> MERCHANTABILITY or FITNESS FOR A PARTICULAR +PURPOSE. See the</p> + +<p style='text-align:justify'> GNU General Public License for more +details.</p> + +<p style='text-align:justify'> You should have received a copy of the GNU +General Public License</p> + +<p style='text-align:justify'> along with this program. If not, see +<https://www.gnu.org/licenses/>.</p> + +<p style='text-align:justify'>Also add information on how to +contact you by electronic and paper mail.</p> + +<p style='text-align:justify'>If the program does terminal +interaction, make it output a short notice like this when it starts in an +interactive mode:</p> + +<p style='text-align:justify'> <program> Copyright (C) <year> +<name of author></p> + +<p style='text-align:justify'> This program comes with ABSOLUTELY NO +WARRANTY; for details type `show w'.</p> + +<p style='text-align:justify'> This is free software, and you are welcome +to redistribute it</p> + +<p style='text-align:justify'> under certain conditions; type `show c' for +details.</p> + +<p style='text-align:justify'>The hypothetical commands `show +w' and `show c' should show the appropriate parts of the General Public +License. Of course, your program's commands might be different; for a GUI +interface, you would use an “about box”.</p> + +<p style='text-align:justify'>You should also get your employer +(if you work as a programmer) or school, if any, to sign a “copyright +disclaimer” for the program, if necessary. For more information on this, and +how to apply and follow the GNU GPL, see <https://www.gnu.org/licenses/>.</p> + +<p style='text-align:justify'>The GNU General Public License +does not permit incorporating your program into proprietary programs. If your +program is a subroutine library, you may consider it more useful to permit +linking proprietary applications with the library. If this is what you want to +do, use the GNU Lesser General Public License instead of this License. But +first, please read <https://www.gnu.org/licenses/why-not-lgpl.html>.</p> + +<p>______________</p> + +<p>COPYING file last revised: July 22, 2022</p> + +</body> + +</html> diff --git a/doc/License-gpl-3.0.rtf b/doc/License-gpl-3.0.rtf new file mode 100644 index 00000000..fa809ace --- /dev/null +++ b/doc/License-gpl-3.0.rtf @@ -0,0 +1,601 @@ +{\rtf1\adeflang1025\ansi\ansicpg1252\uc1\adeff31507\deff0\stshfdbch31506\stshfloch31506\stshfhich31506\stshfbi31507\deflang1033\deflangfe1033\themelang1033\themelangfe0\themelangcs0{\fonttbl{\f0\fbidi \froman\fcharset0\fprq2{\*\panose 02020603050405020304}Times New Roman;}{\f34\fbidi \froman\fcharset0\fprq2{\*\panose 02040503050406030204}Cambria Math;}
+{\f37\fbidi \fswiss\fcharset0\fprq2{\*\panose 020f0502020204030204}Calibri;}{\f43\fbidi \fswiss\fcharset0\fprq2{\*\panose 020b0502040204020203}Segoe UI;}{\flomajor\f31500\fbidi \froman\fcharset0\fprq2{\*\panose 02020603050405020304}Times New Roman;}
+{\fdbmajor\f31501\fbidi \froman\fcharset0\fprq2{\*\panose 02020603050405020304}Times New Roman;}{\fhimajor\f31502\fbidi \fswiss\fcharset0\fprq2{\*\panose 020f0302020204030204}Calibri Light;}
+{\fbimajor\f31503\fbidi \froman\fcharset0\fprq2{\*\panose 02020603050405020304}Times New Roman;}{\flominor\f31504\fbidi \froman\fcharset0\fprq2{\*\panose 02020603050405020304}Times New Roman;}
+{\fdbminor\f31505\fbidi \froman\fcharset0\fprq2{\*\panose 02020603050405020304}Times New Roman;}{\fhiminor\f31506\fbidi \fswiss\fcharset0\fprq2{\*\panose 020f0502020204030204}Calibri;}
+{\fbiminor\f31507\fbidi \froman\fcharset0\fprq2{\*\panose 02020603050405020304}Times New Roman;}{\f44\fbidi \froman\fcharset238\fprq2 Times New Roman CE;}{\f45\fbidi \froman\fcharset204\fprq2 Times New Roman Cyr;}
+{\f47\fbidi \froman\fcharset161\fprq2 Times New Roman Greek;}{\f48\fbidi \froman\fcharset162\fprq2 Times New Roman Tur;}{\f49\fbidi \froman\fcharset177\fprq2 Times New Roman (Hebrew);}{\f50\fbidi \froman\fcharset178\fprq2 Times New Roman (Arabic);}
+{\f51\fbidi \froman\fcharset186\fprq2 Times New Roman Baltic;}{\f52\fbidi \froman\fcharset163\fprq2 Times New Roman (Vietnamese);}{\f414\fbidi \fswiss\fcharset238\fprq2 Calibri CE;}{\f415\fbidi \fswiss\fcharset204\fprq2 Calibri Cyr;}
+{\f417\fbidi \fswiss\fcharset161\fprq2 Calibri Greek;}{\f418\fbidi \fswiss\fcharset162\fprq2 Calibri Tur;}{\f419\fbidi \fswiss\fcharset177\fprq2 Calibri (Hebrew);}{\f420\fbidi \fswiss\fcharset178\fprq2 Calibri (Arabic);}
+{\f421\fbidi \fswiss\fcharset186\fprq2 Calibri Baltic;}{\f422\fbidi \fswiss\fcharset163\fprq2 Calibri (Vietnamese);}{\f474\fbidi \fswiss\fcharset238\fprq2 Segoe UI CE;}{\f475\fbidi \fswiss\fcharset204\fprq2 Segoe UI Cyr;}
+{\f477\fbidi \fswiss\fcharset161\fprq2 Segoe UI Greek;}{\f478\fbidi \fswiss\fcharset162\fprq2 Segoe UI Tur;}{\f479\fbidi \fswiss\fcharset177\fprq2 Segoe UI (Hebrew);}{\f480\fbidi \fswiss\fcharset178\fprq2 Segoe UI (Arabic);}
+{\f481\fbidi \fswiss\fcharset186\fprq2 Segoe UI Baltic;}{\f482\fbidi \fswiss\fcharset163\fprq2 Segoe UI (Vietnamese);}{\flomajor\f31508\fbidi \froman\fcharset238\fprq2 Times New Roman CE;}
+{\flomajor\f31509\fbidi \froman\fcharset204\fprq2 Times New Roman Cyr;}{\flomajor\f31511\fbidi \froman\fcharset161\fprq2 Times New Roman Greek;}{\flomajor\f31512\fbidi \froman\fcharset162\fprq2 Times New Roman Tur;}
+{\flomajor\f31513\fbidi \froman\fcharset177\fprq2 Times New Roman (Hebrew);}{\flomajor\f31514\fbidi \froman\fcharset178\fprq2 Times New Roman (Arabic);}{\flomajor\f31515\fbidi \froman\fcharset186\fprq2 Times New Roman Baltic;}
+{\flomajor\f31516\fbidi \froman\fcharset163\fprq2 Times New Roman (Vietnamese);}{\fdbmajor\f31518\fbidi \froman\fcharset238\fprq2 Times New Roman CE;}{\fdbmajor\f31519\fbidi \froman\fcharset204\fprq2 Times New Roman Cyr;}
+{\fdbmajor\f31521\fbidi \froman\fcharset161\fprq2 Times New Roman Greek;}{\fdbmajor\f31522\fbidi \froman\fcharset162\fprq2 Times New Roman Tur;}{\fdbmajor\f31523\fbidi \froman\fcharset177\fprq2 Times New Roman (Hebrew);}
+{\fdbmajor\f31524\fbidi \froman\fcharset178\fprq2 Times New Roman (Arabic);}{\fdbmajor\f31525\fbidi \froman\fcharset186\fprq2 Times New Roman Baltic;}{\fdbmajor\f31526\fbidi \froman\fcharset163\fprq2 Times New Roman (Vietnamese);}
+{\fhimajor\f31528\fbidi \fswiss\fcharset238\fprq2 Calibri Light CE;}{\fhimajor\f31529\fbidi \fswiss\fcharset204\fprq2 Calibri Light Cyr;}{\fhimajor\f31531\fbidi \fswiss\fcharset161\fprq2 Calibri Light Greek;}
+{\fhimajor\f31532\fbidi \fswiss\fcharset162\fprq2 Calibri Light Tur;}{\fhimajor\f31533\fbidi \fswiss\fcharset177\fprq2 Calibri Light (Hebrew);}{\fhimajor\f31534\fbidi \fswiss\fcharset178\fprq2 Calibri Light (Arabic);}
+{\fhimajor\f31535\fbidi \fswiss\fcharset186\fprq2 Calibri Light Baltic;}{\fhimajor\f31536\fbidi \fswiss\fcharset163\fprq2 Calibri Light (Vietnamese);}{\fbimajor\f31538\fbidi \froman\fcharset238\fprq2 Times New Roman CE;}
+{\fbimajor\f31539\fbidi \froman\fcharset204\fprq2 Times New Roman Cyr;}{\fbimajor\f31541\fbidi \froman\fcharset161\fprq2 Times New Roman Greek;}{\fbimajor\f31542\fbidi \froman\fcharset162\fprq2 Times New Roman Tur;}
+{\fbimajor\f31543\fbidi \froman\fcharset177\fprq2 Times New Roman (Hebrew);}{\fbimajor\f31544\fbidi \froman\fcharset178\fprq2 Times New Roman (Arabic);}{\fbimajor\f31545\fbidi \froman\fcharset186\fprq2 Times New Roman Baltic;}
+{\fbimajor\f31546\fbidi \froman\fcharset163\fprq2 Times New Roman (Vietnamese);}{\flominor\f31548\fbidi \froman\fcharset238\fprq2 Times New Roman CE;}{\flominor\f31549\fbidi \froman\fcharset204\fprq2 Times New Roman Cyr;}
+{\flominor\f31551\fbidi \froman\fcharset161\fprq2 Times New Roman Greek;}{\flominor\f31552\fbidi \froman\fcharset162\fprq2 Times New Roman Tur;}{\flominor\f31553\fbidi \froman\fcharset177\fprq2 Times New Roman (Hebrew);}
+{\flominor\f31554\fbidi \froman\fcharset178\fprq2 Times New Roman (Arabic);}{\flominor\f31555\fbidi \froman\fcharset186\fprq2 Times New Roman Baltic;}{\flominor\f31556\fbidi \froman\fcharset163\fprq2 Times New Roman (Vietnamese);}
+{\fdbminor\f31558\fbidi \froman\fcharset238\fprq2 Times New Roman CE;}{\fdbminor\f31559\fbidi \froman\fcharset204\fprq2 Times New Roman Cyr;}{\fdbminor\f31561\fbidi \froman\fcharset161\fprq2 Times New Roman Greek;}
+{\fdbminor\f31562\fbidi \froman\fcharset162\fprq2 Times New Roman Tur;}{\fdbminor\f31563\fbidi \froman\fcharset177\fprq2 Times New Roman (Hebrew);}{\fdbminor\f31564\fbidi \froman\fcharset178\fprq2 Times New Roman (Arabic);}
+{\fdbminor\f31565\fbidi \froman\fcharset186\fprq2 Times New Roman Baltic;}{\fdbminor\f31566\fbidi \froman\fcharset163\fprq2 Times New Roman (Vietnamese);}{\fhiminor\f31568\fbidi \fswiss\fcharset238\fprq2 Calibri CE;}
+{\fhiminor\f31569\fbidi \fswiss\fcharset204\fprq2 Calibri Cyr;}{\fhiminor\f31571\fbidi \fswiss\fcharset161\fprq2 Calibri Greek;}{\fhiminor\f31572\fbidi \fswiss\fcharset162\fprq2 Calibri Tur;}
+{\fhiminor\f31573\fbidi \fswiss\fcharset177\fprq2 Calibri (Hebrew);}{\fhiminor\f31574\fbidi \fswiss\fcharset178\fprq2 Calibri (Arabic);}{\fhiminor\f31575\fbidi \fswiss\fcharset186\fprq2 Calibri Baltic;}
+{\fhiminor\f31576\fbidi \fswiss\fcharset163\fprq2 Calibri (Vietnamese);}{\fbiminor\f31578\fbidi \froman\fcharset238\fprq2 Times New Roman CE;}{\fbiminor\f31579\fbidi \froman\fcharset204\fprq2 Times New Roman Cyr;}
+{\fbiminor\f31581\fbidi \froman\fcharset161\fprq2 Times New Roman Greek;}{\fbiminor\f31582\fbidi \froman\fcharset162\fprq2 Times New Roman Tur;}{\fbiminor\f31583\fbidi \froman\fcharset177\fprq2 Times New Roman (Hebrew);}
+{\fbiminor\f31584\fbidi \froman\fcharset178\fprq2 Times New Roman (Arabic);}{\fbiminor\f31585\fbidi \froman\fcharset186\fprq2 Times New Roman Baltic;}{\fbiminor\f31586\fbidi \froman\fcharset163\fprq2 Times New Roman (Vietnamese);}}
+{\colortbl;\red0\green0\blue0;\red0\green0\blue255;\red0\green255\blue255;\red0\green255\blue0;\red255\green0\blue255;\red255\green0\blue0;\red255\green255\blue0;\red255\green255\blue255;\red0\green0\blue128;\red0\green128\blue128;\red0\green128\blue0;
+\red128\green0\blue128;\red128\green0\blue0;\red128\green128\blue0;\red128\green128\blue128;\red192\green192\blue192;\red0\green0\blue0;\red0\green0\blue0;}{\*\defchp \f31506\fs22 }{\*\defpap
+\ql \li0\ri0\widctlpar\wrapdefault\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0 }\noqfpromote {\stylesheet{\ql \li0\ri0\widctlpar\wrapdefault\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0 \rtlch\fcs1 \af31507\afs22\alang1025 \ltrch\fcs0
+\f31506\fs22\lang1033\langfe1033\cgrid\langnp1033\langfenp1033 \snext0 \sqformat \spriority0 Normal;}{\*\cs10 \additive \ssemihidden \sunhideused \spriority1 Default Paragraph Font;}{\*
+\ts11\tsrowd\trftsWidthB3\trpaddl108\trpaddr108\trpaddfl3\trpaddft3\trpaddfb3\trpaddfr3\trcbpat1\trcfpat1\tblind0\tblindtype3\tsvertalt\tsbrdrt\tsbrdrl\tsbrdrb\tsbrdrr\tsbrdrdgl\tsbrdrdgr\tsbrdrh\tsbrdrv
+\ql \li0\ri0\widctlpar\wrapdefault\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0 \rtlch\fcs1 \af31507\afs22\alang1025 \ltrch\fcs0 \f31506\fs22\lang1033\langfe1033\cgrid\langnp1033\langfenp1033 \snext11 \ssemihidden \sunhideused Normal Table;}{
+\s15\ql \li0\ri0\widctlpar\wrapdefault\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0 \rtlch\fcs1 \af43\afs18\alang1025 \ltrch\fcs0 \f43\fs18\lang1033\langfe1033\cgrid\langnp1033\langfenp1033
+\sbasedon0 \snext15 \slink16 \ssemihidden \sunhideused \styrsid6191640 Balloon Text;}{\*\cs16 \additive \rtlch\fcs1 \af43\afs18 \ltrch\fcs0 \f43\fs18 \sbasedon10 \slink15 \slocked \ssemihidden \styrsid6191640 Balloon Text Char;}}{\*\rsidtbl \rsid204811
+\rsid1179671\rsid2054772\rsid4488156\rsid5245440\rsid5458651\rsid6191640\rsid6243413\rsid6826983\rsid6827025\rsid7414225\rsid7868682\rsid9137682\rsid9575835\rsid10183799\rsid10356037\rsid13858007\rsid15224405}{\mmathPr\mmathFont34\mbrkBin0\mbrkBinSub0
+\msmallFrac0\mdispDef1\mlMargin0\mrMargin0\mdefJc1\mwrapIndent1440\mintLim0\mnaryLim1}{\*\xmlnstbl {\xmlns1 http://schemas.microsoft.com/office/word/2003/wordml}}\paperw12240\paperh15840\margl1440\margr1440\margt1440\margb1440\gutter0\ltrsect
+\widowctrl\ftnbj\aenddoc\revisions\trackmoves0\trackformatting1\donotembedsysfont1\relyonvml0\donotembedlingdata0\grfdocevents0\validatexml1\showplaceholdtext0\ignoremixedcontent0\saveinvalidxml0\showxmlerrors1
+\noxlattoyen\expshrtn\noultrlspc\dntblnsbdb\nospaceforul\formshade\horzdoc\dgmargin\dghspace180\dgvspace180\dghorigin1440\dgvorigin1440\dghshow1\dgvshow1
+\jexpand\viewkind1\viewscale100\pgbrdrhead\pgbrdrfoot\splytwnine\ftnlytwnine\htmautsp\nolnhtadjtbl\useltbaln\alntblind\lytcalctblwd\lyttblrtgr\lnbrkrule\nobrkwrptbl\snaptogridincell\allowfieldendsel\wrppunct
+\asianbrkrule\rsidroot10183799\newtblstyruls\nogrowautofit\usenormstyforlist\noindnmbrts\felnbrelev\nocxsptable\indrlsweleven\noafcnsttbl\afelev\utinl\hwelev\spltpgpar\notcvasp\notbrkcnstfrctbl\notvatxbx\krnprsnet\cachedcolbal \nouicompat \fet0
+{\*\wgrffmtfilter 2450}\nofeaturethrottle1\ilfomacatclnup0\ltrpar \sectd \ltrsect\linex0\endnhere\sectlinegrid360\sectdefaultcl\sftnbj {\*\pnseclvl1\pnucrm\pnstart1\pnindent720\pnhang {\pntxta .}}{\*\pnseclvl2\pnucltr\pnstart1\pnindent720\pnhang
+{\pntxta .}}{\*\pnseclvl3\pndec\pnstart1\pnindent720\pnhang {\pntxta .}}{\*\pnseclvl4\pnlcltr\pnstart1\pnindent720\pnhang {\pntxta )}}{\*\pnseclvl5\pndec\pnstart1\pnindent720\pnhang {\pntxtb (}{\pntxta )}}{\*\pnseclvl6\pnlcltr\pnstart1\pnindent720\pnhang
+{\pntxtb (}{\pntxta )}}{\*\pnseclvl7\pnlcrm\pnstart1\pnindent720\pnhang {\pntxtb (}{\pntxta )}}{\*\pnseclvl8\pnlcltr\pnstart1\pnindent720\pnhang {\pntxtb (}{\pntxta )}}{\*\pnseclvl9\pnlcrm\pnstart1\pnindent720\pnhang {\pntxtb (}{\pntxta )}}
+\pard\plain \ltrpar\ql \li0\ri0\widctlpar\wrapdefault\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0\pararsid10183799 \rtlch\fcs1 \af31507\afs22\alang1025 \ltrch\fcs0 \f31506\fs22\lang1033\langfe1033\cgrid\langnp1033\langfenp1033 {\rtlch\fcs1
+\af31507 \ltrch\fcs0 \insrsid5245440 COPYING file for VirtualBox versions 7.0 and later versions that include this file
+\par
+\par }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10183799 Preliminary notes:
+\par
+\par }\pard \ltrpar\qj \li0\ri0\widctlpar\wrapdefault\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0\pararsid6191640 {\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10183799 1) }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid6826983
+The majority of the code in the VirtualBox base }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid7414225 package}{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid6826983 is licensed under the GNU General Public License, version 3}{\rtlch\fcs1 \af31507 \ltrch\fcs0
+\insrsid10356037 (GPL)}{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid6826983 .}{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid6826983\charrsid6826983 }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid6826983 VirtualBox contain}{\rtlch\fcs1 \af31507 \ltrch\fcs0
+\insrsid10356037 s}{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid6826983 many components developed by Oracle and various third parties. The license for each component is located in the licensing documentation and/or in the component's source code. }{
+\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10356037 }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid204811
+\par
+\par 2) }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10356037 As an exception to the }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid204811 reciprocal license }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10356037 obligations of the }{\rtlch\fcs1 \af31507 \ltrch\fcs0
+\insrsid10183799\charrsid15224405 GPL listed below}{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10356037 , you may use any }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid5245440 VirtualB}{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10356037
+ox header file that is marked by Oracle as licensed under both the GPL and the Common Development and Distribution License version 1}{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid204811 .}{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10356037 0 (CDDL)}{
+\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10183799\charrsid15224405 }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10356037 t}{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid5245440 o invoke the unmodified VirtualB}{\rtlch\fcs1 \af31507 \ltrch\fcs0
+\insrsid10356037 ox }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid204811 libraries}{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10183799 .}{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid6191640 }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10183799
+In other words, calling such a multi-licensed interface }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid5245440 by dynamically linking to the unmodified VirtualBox libraries }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10183799 is considered}{\rtlch\fcs1
+\af31507 \ltrch\fcs0 \insrsid6191640 }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid204811 a }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10183799 normal use of VirtualBox and does not turn the calling code into a derived work}{\rtlch\fcs1 \af31507
+\ltrch\fcs0 \insrsid6191640 }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10183799 of VirtualBox. }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10183799\charrsid15224405 In particular, this applies to code that wants to extend}{\rtlch\fcs1 \af31507
+\ltrch\fcs0 \insrsid6191640\charrsid15224405 }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10183799\charrsid15224405 VirtualBox by way of the Extension Pack mechanism declared in the ExtPack.h}{\rtlch\fcs1 \af31507 \ltrch\fcs0
+\insrsid6191640\charrsid15224405 }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10183799\charrsid15224405 header file.}{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid1179671 }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid7414225 }{\rtlch\fcs1 \af31507 \ltrch\fcs0
+\insrsid10183799
+\par }\pard \ltrpar\ql \li0\ri0\widctlpar\wrapdefault\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0\pararsid10183799 {\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10183799
+\par }\pard \ltrpar\qj \li0\ri0\widctlpar\wrapdefault\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0\pararsid4488156 {\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid204811 3}{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10183799
+) Whoever creates or distributes a derived work based on VirtualBox is not}{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid6191640 }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10183799 obligated to grant the above exceptions for such a version. The GPL }{
+\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid204811 permits you to release}{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10183799 a modified version without the above exception; in addition, Oracle}{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid6191640 }{
+\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10183799 hereby also allows you to release a modified version which carries forward these}{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid6191640 }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10183799 exceptions.
+\par }\pard \ltrpar\ql \li0\ri0\widctlpar\wrapdefault\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0\pararsid10183799 {\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10183799
+\par }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid5245440
+\par }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10183799 Oracle }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid6827025 America, Inc.}{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid10183799
+\par
+\par ---
+\par
+\par }\pard \ltrpar\ql \li0\ri0\widctlpar\wrapdefault\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0\pararsid6827025 {\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid6191640 G}{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid6827025 NU GENERAL PUBLIC LICENSE
+\par
+\par Version 3, 29 June 2007
+\par
+\par Copyright \'a9 2007 Free Software Foundation, Inc. <https://fsf.org/>
+\par
+\par }\pard \ltrpar\qj \li0\ri0\widctlpar\wrapdefault\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0\pararsid9575835 {\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid6827025
+Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
+\par }\pard \ltrpar\ql \li0\ri0\widctlpar\wrapdefault\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0\pararsid6827025 {\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid9575835
+\par }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid6827025 Preamble
+\par The GNU General Public License is a free, copyleft license for software and other kinds of works.
+\par
+\par }\pard \ltrpar\qj \li0\ri0\widctlpar\wrapdefault\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0\pararsid9575835 {\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid6827025
+The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By
+contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for
+ most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too.
+\par }\pard \ltrpar\ql \li0\ri0\widctlpar\wrapdefault\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0\pararsid6827025 {\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid6827025
+\par }\pard \ltrpar\qj \li0\ri0\widctlpar\wrapdefault\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0\pararsid9575835 {\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid6827025
+When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure
+ that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you
+ can do these things.
+\par }\pard \ltrpar\ql \li0\ri0\widctlpar\wrapdefault\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0\pararsid6827025 {\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid6827025
+\par }\pard \ltrpar\qj \li0\ri0\widctlpar\wrapdefault\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0\pararsid9575835 {\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid6827025
+To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: respons
+ibilities to respect the freedom of others.
+\par
+\par For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get
+ the source code. And you must show them these terms so they know their rights.
+\par
+\par Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it.
+\par
+\par For the developers' and authors' protection, the GPL clearly explains that there is no warranty for this free software. For both users' and authors' sake, the GPL requires that modified versions be marked as changed, so that th
+eir problems will not be attributed erroneously to authors of previous versions.
+\par
+\par Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally inc
+ompatible with the aim of protecting users' freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this vers
+ion of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users.
+\par
+\par Finally, e
+very program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free p
+rogram could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free.
+\par
+\par The precise terms and conditions for copying, distribution and modification follow.
+\par }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid9575835
+\par }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid6827025 TERMS AND CONDITIONS
+\par 0. Definitions.
+\par
+\par \'93This License\'94 refers to version 3 of the GNU General Public License.
+\par
+\par \'93Copyright\'94 also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.
+\par
+\par \'93The Program\'94 refers to any copyrightable work licensed under this License. Each licensee is addressed as \'93you\'94. \'93Licensees\'94 and \'93recipients\'94 may be individuals or organizations.
+\par
+\par To \'93modify\'94 a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a \'93modified version\'94 of the earlier work or a work \'93
+based on\'94 the earlier work.
+\par
+\par A \'93covered work\'94 means either the unmodified Program or a work based on the Program.
+\par
+\par To \'93propagate\'94 a work means to do anything with
+it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modifica
+tion), making available to the public, and in some countries other activities as well.
+\par
+\par To \'93convey\'94 a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying.
+\par
+\par An interactive user interface displays \'93Appropriate Legal Notices\'94 to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user t
+hat there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as
+ a menu, a prominent item in the list meets this criterion.
+\par 1. Source Code.
+\par
+\par The \'93source code\'94 for a work means the preferred form of the work for making modifications to it. \'93Object code\'94 means any non-source form of a work.
+\par
+\par A \'93Standard Interface\'94 means a
+n interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language.
+\par
+\par The \'93System Libraries\'94
+ of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major C
+omponent, or to implement a Standard Interface for which an implementation is available to the public in source code form. A \'93Major Component\'94
+, in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it.
+
+\par
+\par The \'93Corresponding Source\'94 for a work in object code form means all the source code needed to generate, install, and (
+for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmod
+i
+fied in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subpro
+grams that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work.
+\par
+\par The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source.
+\par
+\par The Corresponding Source for a work in source code form is that same work.
+\par 2. Basic Permissions.
+\par
+\par All rights granted under this License are granted for the term of copyright on the Program, and are irrevocab
+le provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a cove
+red work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law.
+\par
+\par You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You
+may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for wh
+i
+ch you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their
+relationship with you.
+\par
+\par Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary.
+\par 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+\par
+\par No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or r
+estricting circumvention of such measures.
+\par
+\par When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the
+ covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures.
+\par 4. Conveying Verbatim Copies.
+\par
+\par You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License an
+d any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program.
+\par
+\par You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee.
+\par 5. Conveying Modified Source Versions.
+\par
+\par You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions:
+\par
+\par a) The work must carry prominent notices stating that you modified it, and giving a relevant date.
+\par b) The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to \'93keep intact all notices\'94.
+\par c) You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. Th
+is License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not
+ invalidate such permission if you have separately received it.
+\par d) If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so.
+\par
+\par A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a
+volume of a storage or distribution medium, is called an \'93aggregate\'94
+ if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered
+work in an aggregate does not cause this License to apply to the other parts of the aggregate.
+\par 6. Conveying Non-Source Forms.
+\par
+\par You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways:
+\par
+\par a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange.
+\par b) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as lo
+ng as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical m
+edium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge.
+\par c) Convey individual cop
+ies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b.
+
+\par d) Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy
+
+the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided y
+o
+u maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these require
+ments.
+\par e) Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d.
+\par
+\par A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work.
+\par
+\par A \'93User Product\'94 is either (1) a \'93consumer product\'94, which means any tangible personal property whi
+ch is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a parti
+cular product received by a particular user, \'93normally used\'94
+ refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to u
+se, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product.
+\par
+\par \'93Installation Information\'94 for a Us
+er Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice t
+o ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made.
+\par
+\par If you convey an object code work under this section in, or with, or specifically for use in, a User P
+roduct, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Correspondin
+g
+ Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work
+has been installed in ROM).
+\par
+\par The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Pro
+duct in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network.
+\par
+\par Corresp
+onding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or ke
+y for unpacking, reading or copying.
+\par 7. Additional Terms.
+\par
+\par \'93Additional permissions\'94 are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program
+ shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire P
+rogram remains governed by this License without regard to the additional permissions.
+\par
+\par When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be
+written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission.
+\par
+\par Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms:
+\par
+\par a) Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or
+\par b) Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or
+\par c) Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or
+\par d) Limiting the use for publicity purposes of names of licensors or authors of the material; or
+\par e) Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or
+\par f) Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions o
+f it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors.
+\par
+\par All other non-permissive additional terms are considered \'93further restrictions\'94
+ within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license docu
+ment contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or
+conveying.
+\par
+\par If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms.
+\par
+\par Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way.
+\par 8. Termination.
+\par
+\par You may not propagate or modify a covered work except as expressly provided un
+der this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11).
+\par
+\par However, if you cease all violation
+ of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you
+of the violation by some reasonable means prior to 60 days after the cessation.
+\par
+\par Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the
+first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
+\par
+\par Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10.
+\par 9. Acceptance Not Required for Having Copies.
+\par
+\par You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise
+does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work,
+ you indicate your acceptance of this License to do so.
+\par 10. Automatic Licensing of Downstream Recipients.
+\par
+\par Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that wor
+k, subject to this License. You are not responsible for enforcing compliance by third parties with this License.
+\par
+\par An \'93entity transaction\'94 is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organi
+zation, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or co
+uld give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts.
+\par
+\par You may not impose any further restrictions on the
+exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or count
+erclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it.
+\par 11. Patents.
+\par
+\par A \'93contributor\'94 is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor's \'93contributor version\'94.
+\par
+\par A contributor's \'93essential patent claims\'94 are all patent claims owned or controlled by the contributor, whether already
+acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the
+ contributor version. For purposes of this definition, \'93control\'94 includes the right to grant patent sublicenses in a manner consistent with the requirements of this License.
+\par
+\par Each contributor grants you a non-exclusive, worldwide, royalty-free patent licens
+e under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version.
+\par
+\par In the following three paragraphs, a \'93patent license\'94 is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To \'93
+grant\'94 such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party.
+\par
+\par If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly
+available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a
+manner consistent with the requirements of this License, to extend the patent license to downstream recipients. \'93Knowingly relying\'94
+ means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recip
+ient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid.
+\par
+\par If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by
+procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatica
+lly extended to all recipients of the covered work and works based on it.
+\par
+\par A patent license is \'93discriminatory\'94 if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the r
+ights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on th
+e
+ extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (o
+r copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007.
+\par
+\par Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law.
+\par 12. No Surrender of Others' Freedom.
+\par
+\par If conditions are imposed on you (wheth
+er by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License
+a
+nd any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satis
+fy both those terms and this License would be to refrain entirely from conveying the Program.
+\par 13. Use with the GNU Affero General Public License.
+\par
+\par Notwithstanding any other provision of this License, you have permission to link or combine any covered work w
+ith a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirement
+s of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such.
+\par 14. Revised Versions of this License.
+\par
+\par The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
+
+\par
+\par Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License \'93or any later version\'94
+ applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation.
+If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation.
+\par
+\par If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program.
+\par
+\par Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version.
+\par 15. Disclaimer of Warranty.
+\par
+\par THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM \'93AS IS\'94
+ WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENT
+IRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+\par 16. Limitation of Liability.
+\par
+\par IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR
+AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INAB
+I
+LITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN A
+DVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+\par 17. Interpretation of Sections 15 and 16.
+\par
+\par If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local la
+w that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee.
+\par
+\par END OF TERMS AND CONDITIONS
+\par How to Apply These Terms to Your New Programs
+\par
+\par If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.
+\par
+\par To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the \'93copyright\'94
+ line and a pointer to where the full notice is found.
+\par
+\par <one line to give the program's name and a brief idea of what it does.>
+\par Copyright (C) <year> <name of author>
+\par
+\par This program is free software: you can redistribute it and/or modify
+\par it under the terms of the GNU General Public License as published by
+\par the Free Software Foundation, either version 3 of the License, or
+\par (at your option) any later version.
+\par
+\par This program is distributed in the hope that it will be useful,
+\par but WITHOUT ANY WARRANTY; without even the implied warranty of
+\par MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+\par GNU General Public License for more details.
+\par
+\par You should have received a copy of the GNU General Public License
+\par along with this program. If not, see <https://www.gnu.org/licenses/>.
+\par
+\par Also add information on how to contact you by electronic and paper mail.
+\par
+\par If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode:
+\par
+\par <program> Copyright (C) <year> <name of author>
+\par This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+\par This is free software, and you are welcome to redistribute it
+\par under certain conditions; type `show c' for details.
+\par
+\par The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, your program's commands might be different; for a GUI interface, you would use an \'93about box\'94.
+\par
+\par You should also get your employer (if you work as a programmer) or school, if any, to sign a \'93copyright disclaimer\'94 for the program, if necessary. For more information on this, and how to apply and follow
+the GNU GPL, see <https://www.gnu.org/licenses/>.
+\par
+\par The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary a
+pplications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read <https://www.gnu.org/licenses/why-not-lgpl.html>.
+\par }\pard \ltrpar\ql \li0\ri0\widctlpar\wrapdefault\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0\pararsid6827025 {\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid5245440
+\par ______________
+\par
+\par }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid9575835 COPYING }{\rtlch\fcs1 \af31507 \ltrch\fcs0 \insrsid5245440 file last revised: July 22, 2022
+\par }{\*\themedata 504b030414000600080000002100e9de0fbfff0000001c020000130000005b436f6e74656e745f54797065735d2e786d6cac91cb4ec3301045f748fc83e52d4a
+9cb2400825e982c78ec7a27cc0c8992416c9d8b2a755fbf74cd25442a820166c2cd933f79e3be372bd1f07b5c3989ca74aaff2422b24eb1b475da5df374fd9ad
+5689811a183c61a50f98f4babebc2837878049899a52a57be670674cb23d8e90721f90a4d2fa3802cb35762680fd800ecd7551dc18eb899138e3c943d7e503b6
+b01d583deee5f99824e290b4ba3f364eac4a430883b3c092d4eca8f946c916422ecab927f52ea42b89a1cd59c254f919b0e85e6535d135a8de20f20b8c12c3b0
+0c895fcf6720192de6bf3b9e89ecdbd6596cbcdd8eb28e7c365ecc4ec1ff1460f53fe813d3cc7f5b7f020000ffff0300504b030414000600080000002100a5d6
+a7e7c0000000360100000b0000005f72656c732f2e72656c73848fcf6ac3300c87ef85bd83d17d51d2c31825762fa590432fa37d00e1287f68221bdb1bebdb4f
+c7060abb0884a4eff7a93dfeae8bf9e194e720169aaa06c3e2433fcb68e1763dbf7f82c985a4a725085b787086a37bdbb55fbc50d1a33ccd311ba548b6309512
+0f88d94fbc52ae4264d1c910d24a45db3462247fa791715fd71f989e19e0364cd3f51652d73760ae8fa8c9ffb3c330cc9e4fc17faf2ce545046e37944c69e462
+a1a82fe353bd90a865aad41ed0b5b8f9d6fd010000ffff0300504b0304140006000800000021006b799616830000008a0000001c0000007468656d652f746865
+6d652f7468656d654d616e616765722e786d6c0ccc4d0ac3201040e17da17790d93763bb284562b2cbaebbf600439c1a41c7a0d29fdbd7e5e38337cedf14d59b
+4b0d592c9c070d8a65cd2e88b7f07c2ca71ba8da481cc52c6ce1c715e6e97818c9b48d13df49c873517d23d59085adb5dd20d6b52bd521ef2cdd5eb9246a3d8b
+4757e8d3f729e245eb2b260a0238fd010000ffff0300504b03041400060008000000210007b740aaca0600008f1a0000160000007468656d652f7468656d652f
+7468656d65312e786d6cec595b8bdb46147e2ff43f08bd3bbe49be2cf1065bb69336bb49889d943cceda636bb2238dd18c776342a0244f7d2914d2d28706fad6
+87521a68a0a12ffd310b1bdaf447f4cc489667ec71f6420aa1640d8b34face996fce39face48ba7aed51449d239c70c2e2965bbe52721d1c8fd898c4d3967b6f
+d82f345c870b148f1165316eb90bccdd6bbb9f7e7215ed881047d801fb98efa0961b0a31db2916f9088611bfc26638866b13964448c069322d8e13740c7e235a
+ac944ab5628448ec3a318ac0ededc9848cb033942edddda5f31e85d358703930a2c940bac68685c28e0fcb12c1173ca089738468cb8579c6ec78881f09d7a188
+0bb8d0724beacf2dee5e2da29dcc888a2db69a5d5ffd657699c1f8b0a2e64ca607f9a49ee77bb576ee5f01a8d8c4f5eabd5aaf96fb5300341ac14a532eba4fbf
+d3ec74fd0cab81d2438bef6ebd5b2d1b78cd7f758373db973f03af40a97f6f03dfef07104503af4029dedfc07b5ebd1278065e81527c6d035f2fb5bb5eddc02b
+5048497cb8812ef9b56ab05c6d0e99307ac30a6ffa5ebf5ec99caf50500d7975c929262c16db6a2d420f59d2078004522448ec88c50c4fd008aa3840941c24c4
+d923d3100a6f8662c661b85429f54b55f82f7f9e3a5211413b1869d6921730e11b43928fc34709998996fb39787535c8e9ebd7274f5f9d3cfdfde4d9b393a7bf
+66732b5786dd0d144f75bbb73f7df3cf8b2f9dbf7ffbf1edf36fd3a9d7f15cc7bff9e5ab377ffcf92ef7b0e255284ebf7bf9e6d5cbd3efbffeebe7e716efed04
+1de8f0218930776ee163e72e8b608116fef820b998c5304444b768c7538e622467b1f8ef89d040df5a208a2cb80e36e3783f01a9b101afcf1f1a8407613217c4
+e2f1661819c07dc6688725d628dc947369611ecee3a97df264aee3ee2274649b3b40b191e5de7c061a4b6c2e83101b34ef50140b34c531168ebcc60e31b6acee
+0121465cf7c928619c4d84f380381d44ac21199203a39a56463748047959d80842be8dd8ecdf773a8cda56ddc5472612ee0d442de487981a61bc8ee602453697
+4314513de07b48843692834532d2713d2e20d3534c99d31b63ce6d36b71358af96f49b2033f6b4efd345642213410e6d3ef710633ab2cb0e831045331b7640e2
+50c77ec60fa144917387091b7c9f9977883c873ca0786bbaef136ca4fb6c35b8070aab535a1588bc324f2cb9bc8e9951bf83059d20aca4061a80a1eb1189cf14
+f93579f7ff3b7907113dfde1856545ef47d2ed8e8d7c5c50ccdb09b1de4d37d6247c1b6e5db803968cc987afdb5d348fef60b855369bd747d9fe28dbeeff5eb6
+b7ddcfef5fac57fa0cd22db7ade9765d6ddea3ad7bf709a174201614ef71b57de7d095c67d189476eab915e7cf72b3100ee59d0c1318b86982948d9330f10511
+e1204433d8e3975de964ca33d753eecc1887adbf1ab6fa96783a8ff6d9387d642d97e5e3692a1e1c89d578c9cfc7e17143a4e85a7df51896bb576ca7ea717949
+40da5e8484369949a26a21515f0eca20a98773089a85845ad97b61d1b4b06848f7cb546db0006a795660dbe4c066abe5fa1e9880113c55218ac7324f69aa97d9
+55c97c9f99de164ca302600fb1ac8055a69b92ebd6e5c9d5a5a5768e4c1b24b4723349a8c8a81ec64334c65975cad1f3d0b868ae9bab941af46428d47c505a2b
+1af5c6bb585c36d760b7ae0d34d69582c6ce71cbad557d2899119ab5dc093cfac3613483dae172bb8be814de9f8d4492def097519659c24517f1300db8129d54
+0d222270e25012b55cb9fc3c0d34561aa2b8952b20081f2cb926c8ca87460e926e26194f267824f4b46b2332d2e929287caa15d6abcafcf26069c9e690ee4138
+3e760ee83cb98ba0c4fc7a5906704c38bc012aa7d11c1378a5990bd9aafed61a5326bbfa3b455543e938a2b310651d4517f314aea43ca7a3cef2186867d99a21
+a05a48b2467830950d560faad14df3ae9172d8da75cf369291d34473d5330d55915dd3ae62c60ccb36b016cbcb35798dd532c4a0697a874fa57b5d729b4bad5b
+db27e45d02029ec7cfd275cfd110346aabc90c6a92f1a60c4bcdce46cddeb15ce019d4ced32434d5af2dddaec52def11d6e960f0529d1fecd6ab168626cb7da5
+8ab4faf6a17f9e60070f413cbaf022784e0557a9848f0f09820dd140ed4952d9805be491c86e0d3872e60969b98f4b7edb0b2a7e502835fc5ec1ab7aa542c36f
+570b6ddfaf967b7eb9d4ed549e4063116154f6d3ef2e7d780d4517d9d71735bef105265abe69bb32625191a92f2c45455c7d812957b67f81710888cee35aa5df
+ac363bb542b3daee17bc6ea7516806b54ea15b0beadd7e37f01bcdfe13d7395260af5d0dbc5aaf51a89583a0e0d54a927ea359a87b954adbabb71b3daffd24db
+c6c0ca53f9c86201e155bc76ff050000ffff0300504b0304140006000800000021000dd1909fb60000001b010000270000007468656d652f7468656d652f5f72
+656c732f7468656d654d616e616765722e786d6c2e72656c73848f4d0ac2301484f78277086f6fd3ba109126dd88d0add40384e4350d363f2451eced0dae2c08
+2e8761be9969bb979dc9136332de3168aa1a083ae995719ac16db8ec8e4052164e89d93b64b060828e6f37ed1567914b284d262452282e3198720e274a939cd0
+8a54f980ae38a38f56e422a3a641c8bbd048f7757da0f19b017cc524bd62107bd5001996509affb3fd381a89672f1f165dfe514173d9850528a2c6cce0239baa
+4c04ca5bbabac4df000000ffff0300504b01022d0014000600080000002100e9de0fbfff0000001c0200001300000000000000000000000000000000005b436f
+6e74656e745f54797065735d2e786d6c504b01022d0014000600080000002100a5d6a7e7c0000000360100000b00000000000000000000000000300100005f72
+656c732f2e72656c73504b01022d00140006000800000021006b799616830000008a0000001c00000000000000000000000000190200007468656d652f746865
+6d652f7468656d654d616e616765722e786d6c504b01022d001400060008000000210007b740aaca0600008f1a00001600000000000000000000000000d60200
+007468656d652f7468656d652f7468656d65312e786d6c504b01022d00140006000800000021000dd1909fb60000001b01000027000000000000000000000000
+00d40900007468656d652f7468656d652f5f72656c732f7468656d654d616e616765722e786d6c2e72656c73504b050600000000050005005d010000cf0a00000000}
+{\*\colorschememapping 3c3f786d6c2076657273696f6e3d22312e302220656e636f64696e673d225554462d3822207374616e64616c6f6e653d22796573223f3e0d0a3c613a636c724d
+617020786d6c6e733a613d22687474703a2f2f736368656d61732e6f70656e786d6c666f726d6174732e6f72672f64726177696e676d6c2f323030362f6d6169
+6e22206267313d226c743122207478313d22646b3122206267323d226c743222207478323d22646b322220616363656e74313d22616363656e74312220616363
+656e74323d22616363656e74322220616363656e74333d22616363656e74332220616363656e74343d22616363656e74342220616363656e74353d22616363656e74352220616363656e74363d22616363656e74362220686c696e6b3d22686c696e6b2220666f6c486c696e6b3d22666f6c486c696e6b222f3e}
+{\*\latentstyles\lsdstimax376\lsdlockeddef0\lsdsemihiddendef0\lsdunhideuseddef0\lsdqformatdef0\lsdprioritydef99{\lsdlockedexcept \lsdqformat1 \lsdpriority0 \lsdlocked0 Normal;\lsdqformat1 \lsdpriority9 \lsdlocked0 heading 1;
+\lsdsemihidden1 \lsdunhideused1 \lsdqformat1 \lsdpriority9 \lsdlocked0 heading 2;\lsdsemihidden1 \lsdunhideused1 \lsdqformat1 \lsdpriority9 \lsdlocked0 heading 3;\lsdsemihidden1 \lsdunhideused1 \lsdqformat1 \lsdpriority9 \lsdlocked0 heading 4;
+\lsdsemihidden1 \lsdunhideused1 \lsdqformat1 \lsdpriority9 \lsdlocked0 heading 5;\lsdsemihidden1 \lsdunhideused1 \lsdqformat1 \lsdpriority9 \lsdlocked0 heading 6;\lsdsemihidden1 \lsdunhideused1 \lsdqformat1 \lsdpriority9 \lsdlocked0 heading 7;
+\lsdsemihidden1 \lsdunhideused1 \lsdqformat1 \lsdpriority9 \lsdlocked0 heading 8;\lsdsemihidden1 \lsdunhideused1 \lsdqformat1 \lsdpriority9 \lsdlocked0 heading 9;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 index 1;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 index 2;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 index 3;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 index 4;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 index 5;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 index 6;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 index 7;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 index 8;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 index 9;
+\lsdsemihidden1 \lsdunhideused1 \lsdpriority39 \lsdlocked0 toc 1;\lsdsemihidden1 \lsdunhideused1 \lsdpriority39 \lsdlocked0 toc 2;\lsdsemihidden1 \lsdunhideused1 \lsdpriority39 \lsdlocked0 toc 3;
+\lsdsemihidden1 \lsdunhideused1 \lsdpriority39 \lsdlocked0 toc 4;\lsdsemihidden1 \lsdunhideused1 \lsdpriority39 \lsdlocked0 toc 5;\lsdsemihidden1 \lsdunhideused1 \lsdpriority39 \lsdlocked0 toc 6;
+\lsdsemihidden1 \lsdunhideused1 \lsdpriority39 \lsdlocked0 toc 7;\lsdsemihidden1 \lsdunhideused1 \lsdpriority39 \lsdlocked0 toc 8;\lsdsemihidden1 \lsdunhideused1 \lsdpriority39 \lsdlocked0 toc 9;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Normal Indent;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 footnote text;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 annotation text;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 header;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 footer;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 index heading;\lsdsemihidden1 \lsdunhideused1 \lsdqformat1 \lsdpriority35 \lsdlocked0 caption;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 table of figures;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 envelope address;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 envelope return;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 footnote reference;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 annotation reference;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 line number;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 page number;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 endnote reference;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 endnote text;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 table of authorities;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 macro;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 toa heading;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 List;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 List Bullet;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 List Number;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 List 2;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 List 3;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 List 4;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 List 5;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 List Bullet 2;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 List Bullet 3;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 List Bullet 4;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 List Bullet 5;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 List Number 2;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 List Number 3;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 List Number 4;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 List Number 5;\lsdqformat1 \lsdpriority10 \lsdlocked0 Title;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Closing;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Signature;\lsdsemihidden1 \lsdunhideused1 \lsdpriority1 \lsdlocked0 Default Paragraph Font;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Body Text;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Body Text Indent;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 List Continue;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 List Continue 2;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 List Continue 3;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 List Continue 4;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 List Continue 5;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Message Header;\lsdqformat1 \lsdpriority11 \lsdlocked0 Subtitle;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Salutation;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Date;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Body Text First Indent;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Body Text First Indent 2;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Note Heading;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Body Text 2;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Body Text 3;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Body Text Indent 2;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Body Text Indent 3;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Block Text;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Hyperlink;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 FollowedHyperlink;\lsdqformat1 \lsdpriority22 \lsdlocked0 Strong;
+\lsdqformat1 \lsdpriority20 \lsdlocked0 Emphasis;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Document Map;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Plain Text;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 E-mail Signature;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 HTML Top of Form;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 HTML Bottom of Form;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Normal (Web);\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 HTML Acronym;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 HTML Address;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 HTML Cite;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 HTML Code;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 HTML Definition;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 HTML Keyboard;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 HTML Preformatted;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 HTML Sample;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 HTML Typewriter;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 HTML Variable;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 annotation subject;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 No List;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Outline List 1;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Outline List 2;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Outline List 3;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Simple 1;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Simple 2;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Simple 3;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Classic 1;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Classic 2;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Classic 3;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Classic 4;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Colorful 1;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Colorful 2;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Colorful 3;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Columns 1;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Columns 2;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Columns 3;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Columns 4;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Columns 5;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Grid 1;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Grid 2;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Grid 3;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Grid 4;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Grid 5;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Grid 6;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Grid 7;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Grid 8;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table List 1;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table List 2;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table List 3;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table List 4;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table List 5;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table List 6;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table List 7;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table List 8;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table 3D effects 1;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table 3D effects 2;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table 3D effects 3;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Contemporary;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Elegant;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Professional;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Subtle 2;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Web 1;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Balloon Text;\lsdpriority39 \lsdlocked0 Table Grid;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Table Theme;\lsdsemihidden1 \lsdlocked0 Placeholder Text;
+\lsdqformat1 \lsdpriority1 \lsdlocked0 No Spacing;\lsdpriority60 \lsdlocked0 Light Shading;\lsdpriority61 \lsdlocked0 Light List;\lsdpriority62 \lsdlocked0 Light Grid;\lsdpriority63 \lsdlocked0 Medium Shading 1;\lsdpriority64 \lsdlocked0 Medium Shading 2;
+\lsdpriority65 \lsdlocked0 Medium List 1;\lsdpriority66 \lsdlocked0 Medium List 2;\lsdpriority67 \lsdlocked0 Medium Grid 1;\lsdpriority68 \lsdlocked0 Medium Grid 2;\lsdpriority69 \lsdlocked0 Medium Grid 3;\lsdpriority70 \lsdlocked0 Dark List;
+\lsdpriority71 \lsdlocked0 Colorful Shading;\lsdpriority72 \lsdlocked0 Colorful List;\lsdpriority73 \lsdlocked0 Colorful Grid;\lsdpriority60 \lsdlocked0 Light Shading Accent 1;\lsdpriority61 \lsdlocked0 Light List Accent 1;
+\lsdpriority62 \lsdlocked0 Light Grid Accent 1;\lsdpriority63 \lsdlocked0 Medium Shading 1 Accent 1;\lsdpriority64 \lsdlocked0 Medium Shading 2 Accent 1;\lsdpriority65 \lsdlocked0 Medium List 1 Accent 1;\lsdsemihidden1 \lsdlocked0 Revision;
+\lsdqformat1 \lsdpriority34 \lsdlocked0 List Paragraph;\lsdqformat1 \lsdpriority29 \lsdlocked0 Quote;\lsdqformat1 \lsdpriority30 \lsdlocked0 Intense Quote;\lsdpriority66 \lsdlocked0 Medium List 2 Accent 1;\lsdpriority67 \lsdlocked0 Medium Grid 1 Accent 1;
+\lsdpriority68 \lsdlocked0 Medium Grid 2 Accent 1;\lsdpriority69 \lsdlocked0 Medium Grid 3 Accent 1;\lsdpriority70 \lsdlocked0 Dark List Accent 1;\lsdpriority71 \lsdlocked0 Colorful Shading Accent 1;\lsdpriority72 \lsdlocked0 Colorful List Accent 1;
+\lsdpriority73 \lsdlocked0 Colorful Grid Accent 1;\lsdpriority60 \lsdlocked0 Light Shading Accent 2;\lsdpriority61 \lsdlocked0 Light List Accent 2;\lsdpriority62 \lsdlocked0 Light Grid Accent 2;\lsdpriority63 \lsdlocked0 Medium Shading 1 Accent 2;
+\lsdpriority64 \lsdlocked0 Medium Shading 2 Accent 2;\lsdpriority65 \lsdlocked0 Medium List 1 Accent 2;\lsdpriority66 \lsdlocked0 Medium List 2 Accent 2;\lsdpriority67 \lsdlocked0 Medium Grid 1 Accent 2;\lsdpriority68 \lsdlocked0 Medium Grid 2 Accent 2;
+\lsdpriority69 \lsdlocked0 Medium Grid 3 Accent 2;\lsdpriority70 \lsdlocked0 Dark List Accent 2;\lsdpriority71 \lsdlocked0 Colorful Shading Accent 2;\lsdpriority72 \lsdlocked0 Colorful List Accent 2;\lsdpriority73 \lsdlocked0 Colorful Grid Accent 2;
+\lsdpriority60 \lsdlocked0 Light Shading Accent 3;\lsdpriority61 \lsdlocked0 Light List Accent 3;\lsdpriority62 \lsdlocked0 Light Grid Accent 3;\lsdpriority63 \lsdlocked0 Medium Shading 1 Accent 3;\lsdpriority64 \lsdlocked0 Medium Shading 2 Accent 3;
+\lsdpriority65 \lsdlocked0 Medium List 1 Accent 3;\lsdpriority66 \lsdlocked0 Medium List 2 Accent 3;\lsdpriority67 \lsdlocked0 Medium Grid 1 Accent 3;\lsdpriority68 \lsdlocked0 Medium Grid 2 Accent 3;\lsdpriority69 \lsdlocked0 Medium Grid 3 Accent 3;
+\lsdpriority70 \lsdlocked0 Dark List Accent 3;\lsdpriority71 \lsdlocked0 Colorful Shading Accent 3;\lsdpriority72 \lsdlocked0 Colorful List Accent 3;\lsdpriority73 \lsdlocked0 Colorful Grid Accent 3;\lsdpriority60 \lsdlocked0 Light Shading Accent 4;
+\lsdpriority61 \lsdlocked0 Light List Accent 4;\lsdpriority62 \lsdlocked0 Light Grid Accent 4;\lsdpriority63 \lsdlocked0 Medium Shading 1 Accent 4;\lsdpriority64 \lsdlocked0 Medium Shading 2 Accent 4;\lsdpriority65 \lsdlocked0 Medium List 1 Accent 4;
+\lsdpriority66 \lsdlocked0 Medium List 2 Accent 4;\lsdpriority67 \lsdlocked0 Medium Grid 1 Accent 4;\lsdpriority68 \lsdlocked0 Medium Grid 2 Accent 4;\lsdpriority69 \lsdlocked0 Medium Grid 3 Accent 4;\lsdpriority70 \lsdlocked0 Dark List Accent 4;
+\lsdpriority71 \lsdlocked0 Colorful Shading Accent 4;\lsdpriority72 \lsdlocked0 Colorful List Accent 4;\lsdpriority73 \lsdlocked0 Colorful Grid Accent 4;\lsdpriority60 \lsdlocked0 Light Shading Accent 5;\lsdpriority61 \lsdlocked0 Light List Accent 5;
+\lsdpriority62 \lsdlocked0 Light Grid Accent 5;\lsdpriority63 \lsdlocked0 Medium Shading 1 Accent 5;\lsdpriority64 \lsdlocked0 Medium Shading 2 Accent 5;\lsdpriority65 \lsdlocked0 Medium List 1 Accent 5;\lsdpriority66 \lsdlocked0 Medium List 2 Accent 5;
+\lsdpriority67 \lsdlocked0 Medium Grid 1 Accent 5;\lsdpriority68 \lsdlocked0 Medium Grid 2 Accent 5;\lsdpriority69 \lsdlocked0 Medium Grid 3 Accent 5;\lsdpriority70 \lsdlocked0 Dark List Accent 5;\lsdpriority71 \lsdlocked0 Colorful Shading Accent 5;
+\lsdpriority72 \lsdlocked0 Colorful List Accent 5;\lsdpriority73 \lsdlocked0 Colorful Grid Accent 5;\lsdpriority60 \lsdlocked0 Light Shading Accent 6;\lsdpriority61 \lsdlocked0 Light List Accent 6;\lsdpriority62 \lsdlocked0 Light Grid Accent 6;
+\lsdpriority63 \lsdlocked0 Medium Shading 1 Accent 6;\lsdpriority64 \lsdlocked0 Medium Shading 2 Accent 6;\lsdpriority65 \lsdlocked0 Medium List 1 Accent 6;\lsdpriority66 \lsdlocked0 Medium List 2 Accent 6;
+\lsdpriority67 \lsdlocked0 Medium Grid 1 Accent 6;\lsdpriority68 \lsdlocked0 Medium Grid 2 Accent 6;\lsdpriority69 \lsdlocked0 Medium Grid 3 Accent 6;\lsdpriority70 \lsdlocked0 Dark List Accent 6;\lsdpriority71 \lsdlocked0 Colorful Shading Accent 6;
+\lsdpriority72 \lsdlocked0 Colorful List Accent 6;\lsdpriority73 \lsdlocked0 Colorful Grid Accent 6;\lsdqformat1 \lsdpriority19 \lsdlocked0 Subtle Emphasis;\lsdqformat1 \lsdpriority21 \lsdlocked0 Intense Emphasis;
+\lsdqformat1 \lsdpriority31 \lsdlocked0 Subtle Reference;\lsdqformat1 \lsdpriority32 \lsdlocked0 Intense Reference;\lsdqformat1 \lsdpriority33 \lsdlocked0 Book Title;\lsdsemihidden1 \lsdunhideused1 \lsdpriority37 \lsdlocked0 Bibliography;
+\lsdsemihidden1 \lsdunhideused1 \lsdqformat1 \lsdpriority39 \lsdlocked0 TOC Heading;\lsdpriority41 \lsdlocked0 Plain Table 1;\lsdpriority42 \lsdlocked0 Plain Table 2;\lsdpriority43 \lsdlocked0 Plain Table 3;\lsdpriority44 \lsdlocked0 Plain Table 4;
+\lsdpriority45 \lsdlocked0 Plain Table 5;\lsdpriority40 \lsdlocked0 Grid Table Light;\lsdpriority46 \lsdlocked0 Grid Table 1 Light;\lsdpriority47 \lsdlocked0 Grid Table 2;\lsdpriority48 \lsdlocked0 Grid Table 3;\lsdpriority49 \lsdlocked0 Grid Table 4;
+\lsdpriority50 \lsdlocked0 Grid Table 5 Dark;\lsdpriority51 \lsdlocked0 Grid Table 6 Colorful;\lsdpriority52 \lsdlocked0 Grid Table 7 Colorful;\lsdpriority46 \lsdlocked0 Grid Table 1 Light Accent 1;\lsdpriority47 \lsdlocked0 Grid Table 2 Accent 1;
+\lsdpriority48 \lsdlocked0 Grid Table 3 Accent 1;\lsdpriority49 \lsdlocked0 Grid Table 4 Accent 1;\lsdpriority50 \lsdlocked0 Grid Table 5 Dark Accent 1;\lsdpriority51 \lsdlocked0 Grid Table 6 Colorful Accent 1;
+\lsdpriority52 \lsdlocked0 Grid Table 7 Colorful Accent 1;\lsdpriority46 \lsdlocked0 Grid Table 1 Light Accent 2;\lsdpriority47 \lsdlocked0 Grid Table 2 Accent 2;\lsdpriority48 \lsdlocked0 Grid Table 3 Accent 2;
+\lsdpriority49 \lsdlocked0 Grid Table 4 Accent 2;\lsdpriority50 \lsdlocked0 Grid Table 5 Dark Accent 2;\lsdpriority51 \lsdlocked0 Grid Table 6 Colorful Accent 2;\lsdpriority52 \lsdlocked0 Grid Table 7 Colorful Accent 2;
+\lsdpriority46 \lsdlocked0 Grid Table 1 Light Accent 3;\lsdpriority47 \lsdlocked0 Grid Table 2 Accent 3;\lsdpriority48 \lsdlocked0 Grid Table 3 Accent 3;\lsdpriority49 \lsdlocked0 Grid Table 4 Accent 3;
+\lsdpriority50 \lsdlocked0 Grid Table 5 Dark Accent 3;\lsdpriority51 \lsdlocked0 Grid Table 6 Colorful Accent 3;\lsdpriority52 \lsdlocked0 Grid Table 7 Colorful Accent 3;\lsdpriority46 \lsdlocked0 Grid Table 1 Light Accent 4;
+\lsdpriority47 \lsdlocked0 Grid Table 2 Accent 4;\lsdpriority48 \lsdlocked0 Grid Table 3 Accent 4;\lsdpriority49 \lsdlocked0 Grid Table 4 Accent 4;\lsdpriority50 \lsdlocked0 Grid Table 5 Dark Accent 4;
+\lsdpriority51 \lsdlocked0 Grid Table 6 Colorful Accent 4;\lsdpriority52 \lsdlocked0 Grid Table 7 Colorful Accent 4;\lsdpriority46 \lsdlocked0 Grid Table 1 Light Accent 5;\lsdpriority47 \lsdlocked0 Grid Table 2 Accent 5;
+\lsdpriority48 \lsdlocked0 Grid Table 3 Accent 5;\lsdpriority49 \lsdlocked0 Grid Table 4 Accent 5;\lsdpriority50 \lsdlocked0 Grid Table 5 Dark Accent 5;\lsdpriority51 \lsdlocked0 Grid Table 6 Colorful Accent 5;
+\lsdpriority52 \lsdlocked0 Grid Table 7 Colorful Accent 5;\lsdpriority46 \lsdlocked0 Grid Table 1 Light Accent 6;\lsdpriority47 \lsdlocked0 Grid Table 2 Accent 6;\lsdpriority48 \lsdlocked0 Grid Table 3 Accent 6;
+\lsdpriority49 \lsdlocked0 Grid Table 4 Accent 6;\lsdpriority50 \lsdlocked0 Grid Table 5 Dark Accent 6;\lsdpriority51 \lsdlocked0 Grid Table 6 Colorful Accent 6;\lsdpriority52 \lsdlocked0 Grid Table 7 Colorful Accent 6;
+\lsdpriority46 \lsdlocked0 List Table 1 Light;\lsdpriority47 \lsdlocked0 List Table 2;\lsdpriority48 \lsdlocked0 List Table 3;\lsdpriority49 \lsdlocked0 List Table 4;\lsdpriority50 \lsdlocked0 List Table 5 Dark;
+\lsdpriority51 \lsdlocked0 List Table 6 Colorful;\lsdpriority52 \lsdlocked0 List Table 7 Colorful;\lsdpriority46 \lsdlocked0 List Table 1 Light Accent 1;\lsdpriority47 \lsdlocked0 List Table 2 Accent 1;\lsdpriority48 \lsdlocked0 List Table 3 Accent 1;
+\lsdpriority49 \lsdlocked0 List Table 4 Accent 1;\lsdpriority50 \lsdlocked0 List Table 5 Dark Accent 1;\lsdpriority51 \lsdlocked0 List Table 6 Colorful Accent 1;\lsdpriority52 \lsdlocked0 List Table 7 Colorful Accent 1;
+\lsdpriority46 \lsdlocked0 List Table 1 Light Accent 2;\lsdpriority47 \lsdlocked0 List Table 2 Accent 2;\lsdpriority48 \lsdlocked0 List Table 3 Accent 2;\lsdpriority49 \lsdlocked0 List Table 4 Accent 2;
+\lsdpriority50 \lsdlocked0 List Table 5 Dark Accent 2;\lsdpriority51 \lsdlocked0 List Table 6 Colorful Accent 2;\lsdpriority52 \lsdlocked0 List Table 7 Colorful Accent 2;\lsdpriority46 \lsdlocked0 List Table 1 Light Accent 3;
+\lsdpriority47 \lsdlocked0 List Table 2 Accent 3;\lsdpriority48 \lsdlocked0 List Table 3 Accent 3;\lsdpriority49 \lsdlocked0 List Table 4 Accent 3;\lsdpriority50 \lsdlocked0 List Table 5 Dark Accent 3;
+\lsdpriority51 \lsdlocked0 List Table 6 Colorful Accent 3;\lsdpriority52 \lsdlocked0 List Table 7 Colorful Accent 3;\lsdpriority46 \lsdlocked0 List Table 1 Light Accent 4;\lsdpriority47 \lsdlocked0 List Table 2 Accent 4;
+\lsdpriority48 \lsdlocked0 List Table 3 Accent 4;\lsdpriority49 \lsdlocked0 List Table 4 Accent 4;\lsdpriority50 \lsdlocked0 List Table 5 Dark Accent 4;\lsdpriority51 \lsdlocked0 List Table 6 Colorful Accent 4;
+\lsdpriority52 \lsdlocked0 List Table 7 Colorful Accent 4;\lsdpriority46 \lsdlocked0 List Table 1 Light Accent 5;\lsdpriority47 \lsdlocked0 List Table 2 Accent 5;\lsdpriority48 \lsdlocked0 List Table 3 Accent 5;
+\lsdpriority49 \lsdlocked0 List Table 4 Accent 5;\lsdpriority50 \lsdlocked0 List Table 5 Dark Accent 5;\lsdpriority51 \lsdlocked0 List Table 6 Colorful Accent 5;\lsdpriority52 \lsdlocked0 List Table 7 Colorful Accent 5;
+\lsdpriority46 \lsdlocked0 List Table 1 Light Accent 6;\lsdpriority47 \lsdlocked0 List Table 2 Accent 6;\lsdpriority48 \lsdlocked0 List Table 3 Accent 6;\lsdpriority49 \lsdlocked0 List Table 4 Accent 6;
+\lsdpriority50 \lsdlocked0 List Table 5 Dark Accent 6;\lsdpriority51 \lsdlocked0 List Table 6 Colorful Accent 6;\lsdpriority52 \lsdlocked0 List Table 7 Colorful Accent 6;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Mention;
+\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Smart Hyperlink;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Hashtag;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Unresolved Mention;\lsdsemihidden1 \lsdunhideused1 \lsdlocked0 Smart Link;}}{\*\datastore 01050000
+02000000180000004d73786d6c322e534158584d4c5265616465722e362e30000000000000000000000e0000
+d0cf11e0a1b11ae1000000000000000000000000000000003e000300feff0900060000000000000000000000010000000100000000000000001000000200000001000000feffffff0000000000000000ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+fffffffffffffffffdffffff04000000feffffff05000000fefffffffeffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+ffffffffffffffffffffffffffffffff52006f006f007400200045006e00740072007900000000000000000000000000000000000000000000000000000000000000000000000000000000000000000016000500ffffffffffffffff010000000c6ad98892f1d411a65f0040963251e5000000000000000000000000508c
+c4d033a8d80103000000c0020000000000004d0073006f004400610074006100530074006f0072006500000000000000000000000000000000000000000000000000000000000000000000000000000000001a000101ffffffffffffffff020000000000000000000000000000000000000000000000508cc4d033a8d801
+508cc4d033a8d801000000000000000000000000de00590055005100d70053005200c600cc00d4004700ce005500dc005300ce00c200d900500033003000c0003d003d000000000000000000000000000000000032000101ffffffffffffffff030000000000000000000000000000000000000000000000508cc4d033a8
+d801508cc4d033a8d8010000000000000000000000004900740065006d0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a000201ffffffff04000000ffffffff000000000000000000000000000000000000000000000000
+00000000000000000000000000000000320100000000000001000000020000000300000004000000feffffff060000000700000008000000090000000a000000feffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff3c3f786d6c2076657273696f6e3d22312e302220656e636f64696e673d225554462d3822207374616e64616c6f6e653d226e6f223f3e3c623a536f757263657320786d6c6e733a623d22687474703a2f2f736368656d61732e6f70656e78
+6d6c666f726d6174732e6f72672f6f6666696365446f63756d656e742f323030362f6269626c696f6772617068792220786d6c6e733d22687474703a2f2f736368656d61732e6f70656e786d6c666f726d6174732e6f72672f6f6666696365446f63756d656e742f323030362f6269626c696f677261706879222053656c
+65637465645374796c653d225c415041536978746845646974696f6e4f66666963654f6e6c696e652e78736c22205374796c654e616d653d22415041222056657273696f6e3d2236223e3c2f623a536f75726365733e00000000000000000000000000003c3f786d6c2076657273696f6e3d22312e302220656e636f6469
+6e673d225554462d3822207374616e64616c6f6e653d226e6f223f3e0d0a3c64733a6461746173746f72654974656d2064733a6974656d49443d227b44443130383546392d363632342d343142332d414535332d4334414538423933444436417d2220786d6c6e733a64733d22687474703a2f2f736368656d61732e6f70
+656e786d6c666f726d6174732e6f72672f6f6666696365446f63756d656e742f323030362f637573500072006f007000650072007400690065007300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000016000200ffffffffffffffffffffffff000000000000
+0000000000000000000000000000000000000000000000000000000000000500000055010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000ffffffffffffffffffffffff00000000
+00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000ffffffffffffffffffffffff0000
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000ffffffffffffffffffffffff
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000746f6d586d6c223e3c64733a736368656d61526566733e3c64733a736368656d615265662064733a7572693d22687474703a2f2f736368656d61732e6f70656e786d6c666f726d6174732e6f7267
+2f6f6666696365446f63756d656e742f323030362f6269626c696f677261706879222f3e3c2f64733a736368656d61526566733e3c2f64733a6461746173746f72654974656d3e00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000105000000000000}}
diff --git a/doc/License-gpl-3.0.txt b/doc/License-gpl-3.0.txt new file mode 100644 index 00000000..04c3dc83 --- /dev/null +++ b/doc/License-gpl-3.0.txt @@ -0,0 +1,663 @@ +OPYING file for VirtualBox versions 7.0 and later versions that include this +file + +Preliminary notes: + +1) The majority of the code in the VirtualBox base package is licensed under +the GNU General Public License, version 3 (GPL). VirtualBox contains many +components developed by Oracle and various third parties. The license for +each component is located in the licensing documentation and/or in the +component's source code. + +2) As an exception to the reciprocal license obligations of the GPL listed +below, you may use any VirtualBox header file that is marked by Oracle as +licensed under both the GPL and the Common Development and Distribution +License version 1.0 (CDDL) to invoke the unmodified VirtualBox libraries. In +other words, calling such a multi-licensed interface by dynamically linking +to the unmodified VirtualBox libraries is considered a normal use of +VirtualBox and does not turn the calling code into a derived work of +VirtualBox. In particular, this applies to code that wants to extend +VirtualBox by way of the Extension Pack mechanism declared in the ExtPack.h +header file. + +3) Whoever creates or distributes a derived work based on VirtualBox is not +obligated to grant the above exceptions for such a version. The GPL permits +you to release a modified version without the above exception; in addition, +Oracle hereby also allows you to release a modified version which carries +forward these exceptions. + + +Oracle America, Inc. + +--- + +GNU GENERAL PUBLIC LICENSE + +Version 3, 29 June 2007 + +Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/> + +Everyone is permitted to copy and distribute verbatim copies of this license +document, but changing it is not allowed. + +Preamble +The GNU General Public License is a free, copyleft license for software and +other kinds of works. + +The licenses for most software and other practical works are designed to take +away your freedom to share and change the works. By contrast, the GNU General +Public License is intended to guarantee your freedom to share and change all +versions of a program--to make sure it remains free software for all its +users. We, the Free Software Foundation, use the GNU General Public License +for most of our software; it applies also to any other work released this way +by its authors. You can apply it to your programs, too. + +When we speak of free software, we are referring to freedom, not price. Our +General Public Licenses are designed to make sure that you have the freedom +to distribute copies of free software (and charge for them if you wish), that +you receive source code or can get it if you want it, that you can change the +software or use pieces of it in new free programs, and that you know you can +do these things. + +To protect your rights, we need to prevent others from denying you these +rights or asking you to surrender the rights. Therefore, you have certain +responsibilities if you distribute copies of the software, or if you modify +it: responsibilities to respect the freedom of others. + +For example, if you distribute copies of such a program, whether gratis or +for a fee, you must pass on to the recipients the same freedoms that you +received. You must make sure that they, too, receive or can get the source +code. And you must show them these terms so they know their rights. + +Developers that use the GNU GPL protect your rights with two steps: (1) +assert copyright on the software, and (2) offer you this License giving you +legal permission to copy, distribute and/or modify it. + +For the developers' and authors' protection, the GPL clearly explains that +there is no warranty for this free software. For both users' and authors' +sake, the GPL requires that modified versions be marked as changed, so that +their problems will not be attributed erroneously to authors of previous +versions. + +Some devices are designed to deny users access to install or run modified +versions of the software inside them, although the manufacturer can do so. +This is fundamentally incompatible with the aim of protecting users' freedom +to change the software. The systematic pattern of such abuse occurs in the +area of products for individuals to use, which is precisely where it is most +unacceptable. Therefore, we have designed this version of the GPL to prohibit +the practice for those products. If such problems arise substantially in +other domains, we stand ready to extend this provision to those domains in +future versions of the GPL, as needed to protect the freedom of users. + +Finally, every program is threatened constantly by software patents. States +should not allow patents to restrict development and use of software on +general-purpose computers, but in those that do, we wish to avoid the special +danger that patents applied to a free program could make it effectively +proprietary. To prevent this, the GPL assures that patents cannot be used to +render the program non-free. + +The precise terms and conditions for copying, distribution and modification +follow. + +TERMS AND CONDITIONS + +0. Definitions. + +"This License" refers to version 3 of the GNU General Public License. + +"Copyright" also means copyright-like laws that apply to other kinds of +works, such as semiconductor masks. + +"The Program" refers to any copyrightable work licensed under this License. +Each licensee is addressed as "you". "Licensees" and "recipients" may be +individuals or organizations. + +To "modify" a work means to copy from or adapt all or part of the work in a +fashion requiring copyright permission, other than the making of an exact +copy. The resulting work is called a "modified version" of the earlier work +or a work "based on" the earlier work. + +A "covered work" means either the unmodified Program or a work based on the +Program. + +To "propagate" a work means to do anything with it that, without permission, +would make you directly or secondarily liable for infringement under +applicable copyright law, except executing it on a computer or modifying a +private copy. Propagation includes copying, distribution (with or without +modification), making available to the public, and in some countries other +activities as well. + +To "convey" a work means any kind of propagation that enables other parties +to make or receive copies. Mere interaction with a user through a computer +network, with no transfer of a copy, is not conveying. + +An interactive user interface displays "Appropriate Legal Notices" to the +extent that it includes a convenient and prominently visible feature that (1) +displays an appropriate copyright notice, and (2) tells the user that there +is no warranty for the work (except to the extent that warranties are +provided), that licensees may convey the work under this License, and how to +view a copy of this License. If the interface presents a list of user +commands or options, such as a menu, a prominent item in the list meets this +criterion. + +1. Source Code. + +The "source code" for a work means the preferred form of the work for making +modifications to it. "Object code" means any non-source form of a work. + +A "Standard Interface" means an interface that either is an official standard +defined by a recognized standards body, or, in the case of interfaces +specified for a particular programming language, one that is widely used +among developers working in that language. + +The "System Libraries" of an executable work include anything, other than the +work as a whole, that (a) is included in the normal form of packaging a Major +Component, but which is not part of that Major Component, and (b) serves only +to enable use of the work with that Major Component, or to implement a +Standard Interface for which an implementation is available to the public in +source code form. A "Major Component", in this context, means a major +essential component (kernel, window system, and so on) of the specific +operating system (if any) on which the executable work runs, or a compiler +used to produce the work, or an object code interpreter used to run it. + +The "Corresponding Source" for a work in object code form means all the +source code needed to generate, install, and (for an executable work) run the +object code and to modify the work, including scripts to control those +activities. However, it does not include the work's System Libraries, or +general-purpose tools or generally available free programs which are used +unmodified in performing those activities but which are not part of the work. +For example, Corresponding Source includes interface definition files +associated with source files for the work, and the source code for shared +libraries and dynamically linked subprograms that the work is specifically +designed to require, such as by intimate data communication or control flow +between those subprograms and other parts of the work. + +The Corresponding Source need not include anything that users can regenerate +automatically from other parts of the Corresponding Source. + +The Corresponding Source for a work in source code form is that same work. + +2. Basic Permissions. + +All rights granted under this License are granted for the term of copyright +on the Program, and are irrevocable provided the stated conditions are met. +This License explicitly affirms your unlimited permission to run the +unmodified Program. The output from running a covered work is covered by this +License only if the output, given its content, constitutes a covered work. +This License acknowledges your rights of fair use or other equivalent, as +provided by copyright law. + +You may make, run and propagate covered works that you do not convey, without +conditions so long as your license otherwise remains in force. You may convey +covered works to others for the sole purpose of having them make +modifications exclusively for you, or provide you with facilities for running +those works, provided that you comply with the terms of this License in +conveying all material for which you do not control copyright. Those thus +making or running the covered works for you must do so exclusively on your +behalf, under your direction and control, on terms that prohibit them from +making any copies of your copyrighted material outside their relationship +with you. + +Conveying under any other circumstances is permitted solely under the +conditions stated below. Sublicensing is not allowed; section 10 makes it +unnecessary. + +3. Protecting Users' Legal Rights From Anti-Circumvention Law. + +No covered work shall be deemed part of an effective technological measure +under any applicable law fulfilling obligations under article 11 of the WIPO +copyright treaty adopted on 20 December 1996, or similar laws prohibiting or +restricting circumvention of such measures. + +When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such circumvention is +effected by exercising rights under this License with respect to the covered +work, and you disclaim any intention to limit operation or modification of +the work as a means of enforcing, against the work's users, your or third +parties' legal rights to forbid circumvention of technological measures. + +4. Conveying Verbatim Copies. + +You may convey verbatim copies of the Program's source code as you receive +it, in any medium, provided that you conspicuously and appropriately publish +on each copy an appropriate copyright notice; keep intact all notices stating +that this License and any non-permissive terms added in accord with section 7 +apply to the code; keep intact all notices of the absence of any warranty; +and give all recipients a copy of this License along with the Program. + +You may charge any price or no price for each copy that you convey, and you +may offer support or warranty protection for a fee. + +5. Conveying Modified Source Versions. + +You may convey a work based on the Program, or the modifications to produce +it from the Program, in the form of source code under the terms of section 4, +provided that you also meet all of these conditions: + + a) The work must carry prominent notices stating that you modified it, +and giving a relevant date. + b) The work must carry prominent notices stating that it is released +under this License and any conditions added under section 7. This requirement +modifies the requirement in section 4 to "keep intact all notices". + c) You must license the entire work, as a whole, under this License to +anyone who comes into possession of a copy. This License will therefore +apply, along with any applicable section 7 additional terms, to the whole of +the work, and all its parts, regardless of how they are packaged. This +License gives no permission to license the work in any other way, but it does +not invalidate such permission if you have separately received it. + d) If the work has interactive user interfaces, each must display +Appropriate Legal Notices; however, if the Program has interactive interfaces +that do not display Appropriate Legal Notices, your work need not make them +do so. + +A compilation of a covered work with other separate and independent works, +which are not by their nature extensions of the covered work, and which are +not combined with it such as to form a larger program, in or on a volume of a +storage or distribution medium, is called an "aggregate" if the compilation +and its resulting copyright are not used to limit the access or legal rights +of the compilation's users beyond what the individual works permit. Inclusion +of a covered work in an aggregate does not cause this License to apply to the +other parts of the aggregate. + +6. Conveying Non-Source Forms. + +You may convey a covered work in object code form under the terms of sections +4 and 5, provided that you also convey the machine-readable Corresponding +Source under the terms of this License, in one of these ways: + + a) Convey the object code in, or embodied in, a physical product +(including a physical distribution medium), accompanied by the Corresponding +Source fixed on a durable physical medium customarily used for software +interchange. + b) Convey the object code in, or embodied in, a physical product +(including a physical distribution medium), accompanied by a written offer, +valid for at least three years and valid for as long as you offer spare parts +or customer support for that product model, to give anyone who possesses the +object code either (1) a copy of the Corresponding Source for all the +software in the product that is covered by this License, on a durable +physical medium customarily used for software interchange, for a price no +more than your reasonable cost of physically performing this conveying of +source, or (2) access to copy the Corresponding Source from a network server +at no charge. + c) Convey individual copies of the object code with a copy of the written +offer to provide the Corresponding Source. This alternative is allowed only +occasionally and noncommercially, and only if you received the object code +with such an offer, in accord with subsection 6b. + d) Convey the object code by offering access from a designated place +(gratis or for a charge), and offer equivalent access to the Corresponding +Source in the same way through the same place at no further charge. You need +not require recipients to copy the Corresponding Source along with the object +code. If the place to copy the object code is a network server, the +Corresponding Source may be on a different server (operated by you or a third +party) that supports equivalent copying facilities, provided you maintain +clear directions next to the object code saying where to find the +Corresponding Source. Regardless of what server hosts the Corresponding +Source, you remain obligated to ensure that it is available for as long as +needed to satisfy these requirements. + e) Convey the object code using peer-to-peer transmission, provided you +inform other peers where the object code and Corresponding Source of the work +are being offered to the general public at no charge under subsection 6d. + +A separable portion of the object code, whose source code is excluded from +the Corresponding Source as a System Library, need not be included in +conveying the object code work. + +A "User Product" is either (1) a "consumer product", which means any tangible +personal property which is normally used for personal, family, or household +purposes, or (2) anything designed or sold for incorporation into a dwelling. +In determining whether a product is a consumer product, doubtful cases shall +be resolved in favor of coverage. For a particular product received by a +particular user, "normally used" refers to a typical or common use of that +class of product, regardless of the status of the particular user or of the +way in which the particular user actually uses, or expects or is expected to +use, the product. A product is a consumer product regardless of whether the +product has substantial commercial, industrial or non-consumer uses, unless +such uses represent the only significant mode of use of the product. + +"Installation Information" for a User Product means any methods, procedures, +authorization keys, or other information required to install and execute +modified versions of a covered work in that User Product from a modified +version of its Corresponding Source. The information must suffice to ensure +that the continued functioning of the modified object code is in no case +prevented or interfered with solely because modification has been made. + +If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as part of +a transaction in which the right of possession and use of the User Product is +transferred to the recipient in perpetuity or for a fixed term (regardless of +how the transaction is characterized), the Corresponding Source conveyed +under this section must be accompanied by the Installation Information. But +this requirement does not apply if neither you nor any third party retains +the ability to install modified object code on the User Product (for example, +the work has been installed in ROM). + +The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or updates for +a work that has been modified or installed by the recipient, or for the User +Product in which it has been modified or installed. Access to a network may +be denied when the modification itself materially and adversely affects the +operation of the network or violates the rules and protocols for +communication across the network. + +Corresponding Source conveyed, and Installation Information provided, in +accord with this section must be in a format that is publicly documented (and +with an implementation available to the public in source code form), and must +require no special password or key for unpacking, reading or copying. + +7. Additional Terms. + +"Additional permissions" are terms that supplement the terms of this License +by making exceptions from one or more of its conditions. Additional +permissions that are applicable to the entire Program shall be treated as +though they were included in this License, to the extent that they are valid +under applicable law. If additional permissions apply only to part of the +Program, that part may be used separately under those permissions, but the +entire Program remains governed by this License without regard to the +additional permissions. + +When you convey a copy of a covered work, you may at your option remove any +additional permissions from that copy, or from any part of it. (Additional +permissions may be written to require their own removal in certain cases when +you modify the work.) You may place additional permissions on material, added +by you to a covered work, for which you have or can give appropriate +copyright permission. + +Notwithstanding any other provision of this License, for material you add to +a covered work, you may (if authorized by the copyright holders of that +material) supplement the terms of this License with terms: + + a) Disclaiming warranty or limiting liability differently from the terms +of sections 15 and 16 of this License; or + b) Requiring preservation of specified reasonable legal notices or author +attributions in that material or in the Appropriate Legal Notices displayed +by works containing it; or + c) Prohibiting misrepresentation of the origin of that material, or +requiring that modified versions of such material be marked in reasonable +ways as different from the original version; or + d) Limiting the use for publicity purposes of names of licensors or +authors of the material; or + e) Declining to grant rights under trademark law for use of some trade +names, trademarks, or service marks; or + f) Requiring indemnification of licensors and authors of that material by +anyone who conveys the material (or modified versions of it) with contractual +assumptions of liability to the recipient, for any liability that these +contractual assumptions directly impose on those licensors and authors. + +All other non-permissive additional terms are considered "further +restrictions" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is governed +by this License along with a term that is a further restriction, you may +remove that term. If a license document contains a further restriction but +permits relicensing or conveying under this License, you may add to a covered +work material governed by the terms of that license document, provided that +the further restriction does not survive such relicensing or conveying. + +If you add terms to a covered work in accord with this section, you must +place, in the relevant source files, a statement of the additional terms that +apply to those files, or a notice indicating where to find the applicable +terms. + +Additional terms, permissive or non-permissive, may be stated in the form of +a separately written license, or stated as exceptions; the above requirements +apply either way. + +8. Termination. + +You may not propagate or modify a covered work except as expressly provided +under this License. Any attempt otherwise to propagate or modify it is void, +and will automatically terminate your rights under this License (including +any patent licenses granted under the third paragraph of section 11). + +However, if you cease all violation of this License, then your license from a +particular copyright holder is reinstated (a) provisionally, unless and until +the copyright holder explicitly and finally terminates your license, and (b) +permanently, if the copyright holder fails to notify you of the violation by +some reasonable means prior to 60 days after the cessation. + +Moreover, your license from a particular copyright holder is reinstated +permanently if the copyright holder notifies you of the violation by some +reasonable means, this is the first time you have received notice of +violation of this License (for any work) from that copyright holder, and you +cure the violation prior to 30 days after your receipt of the notice. + +Termination of your rights under this section does not terminate the licenses +of parties who have received copies or rights from you under this License. If +your rights have been terminated and not permanently reinstated, you do not +qualify to receive new licenses for the same material under section 10. + +9. Acceptance Not Required for Having Copies. + +You are not required to accept this License in order to receive or run a copy +of the Program. Ancillary propagation of a covered work occurring solely as a +consequence of using peer-to-peer transmission to receive a copy likewise +does not require acceptance. However, nothing other than this License grants +you permission to propagate or modify any covered work. These actions +infringe copyright if you do not accept this License. Therefore, by modifying +or propagating a covered work, you indicate your acceptance of this License +to do so. + +10. Automatic Licensing of Downstream Recipients. + +Each time you convey a covered work, the recipient automatically receives a +license from the original licensors, to run, modify and propagate that work, +subject to this License. You are not responsible for enforcing compliance by +third parties with this License. + +An "entity transaction" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered work +results from an entity transaction, each party to that transaction who +receives a copy of the work also receives whatever licenses to the work the +party's predecessor in interest had or could give under the previous +paragraph, plus a right to possession of the Corresponding Source of the work +from the predecessor in interest, if the predecessor has it or can get it +with reasonable efforts. + +You may not impose any further restrictions on the exercise of the rights +granted or affirmed under this License. For example, you may not impose a +license fee, royalty, or other charge for exercise of rights granted under +this License, and you may not initiate litigation (including a cross-claim or +counterclaim in a lawsuit) alleging that any patent claim is infringed by +making, using, selling, offering for sale, or importing the Program or any +portion of it. + +11. Patents. + +A "contributor" is a copyright holder who authorizes use under this License +of the Program or a work on which the Program is based. The work thus +licensed is called the contributor's "contributor version". + +A contributor's "essential patent claims" are all patent claims owned or +controlled by the contributor, whether already acquired or hereafter +acquired, that would be infringed by some manner, permitted by this License, +of making, using, or selling its contributor version, but do not include +claims that would be infringed only as a consequence of further modification +of the contributor version. For purposes of this definition, "control" +includes the right to grant patent sublicenses in a manner consistent with +the requirements of this License. + +Each contributor grants you a non-exclusive, worldwide, royalty-free patent +license under the contributor's essential patent claims, to make, use, sell, +offer for sale, import and otherwise run, modify and propagate the contents +of its contributor version. + +In the following three paragraphs, a "patent license" is any express +agreement or commitment, however denominated, not to enforce a patent (such +as an express permission to practice a patent or covenant not to sue for +patent infringement). To "grant" such a patent license to a party means to +make such an agreement or commitment not to enforce a patent against the +party. + +If you convey a covered work, knowingly relying on a patent license, and the +Corresponding Source of the work is not available for anyone to copy, free of +charge and under the terms of this License, through a publicly available +network server or other readily accessible means, then you must either (1) +cause the Corresponding Source to be so available, or (2) arrange to deprive +yourself of the benefit of the patent license for this particular work, or +(3) arrange, in a manner consistent with the requirements of this License, to +extend the patent license to downstream recipients. "Knowingly relying" means +you have actual knowledge that, but for the patent license, your conveying +the covered work in a country, or your recipient's use of the covered work in +a country, would infringe one or more identifiable patents in that country +that you have reason to believe are valid. + +If, pursuant to or in connection with a single transaction or arrangement, +you convey, or propagate by procuring conveyance of, a covered work, and +grant a patent license to some of the parties receiving the covered work +authorizing them to use, propagate, modify or convey a specific copy of the +covered work, then the patent license you grant is automatically extended to +all recipients of the covered work and works based on it. + +A patent license is "discriminatory" if it does not include within the scope +of its coverage, prohibits the exercise of, or is conditioned on the non- +exercise of one or more of the rights that are specifically granted under +this License. You may not convey a covered work if you are a party to an +arrangement with a third party that is in the business of distributing +software, under which you make payment to the third party based on the extent +of your activity of conveying the work, and under which the third party +grants, to any of the parties who would receive the covered work from you, a +discriminatory patent license (a) in connection with copies of the covered +work conveyed by you (or copies made from those copies), or (b) primarily for +and in connection with specific products or compilations that contain the +covered work, unless you entered into that arrangement, or that patent +license was granted, prior to 28 March 2007. + +Nothing in this License shall be construed as excluding or limiting any +implied license or other defenses to infringement that may otherwise be +available to you under applicable patent law. + +12. No Surrender of Others' Freedom. + +If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not excuse +you from the conditions of this License. If you cannot convey a covered work +so as to satisfy simultaneously your obligations under this License and any +other pertinent obligations, then as a consequence you may not convey it at +all. For example, if you agree to terms that obligate you to collect a +royalty for further conveying from those to whom you convey the Program, the +only way you could satisfy both those terms and this License would be to +refrain entirely from conveying the Program. + +13. Use with the GNU Affero General Public License. + +Notwithstanding any other provision of this License, you have permission to +link or combine any covered work with a work licensed under version 3 of the +GNU Affero General Public License into a single combined work, and to convey +the resulting work. The terms of this License will continue to apply to the +part which is the covered work, but the special requirements of the GNU +Affero General Public License, section 13, concerning interaction through a +network will apply to the combination as such. + +14. Revised Versions of this License. + +The Free Software Foundation may publish revised and/or new versions of the +GNU General Public License from time to time. Such new versions will be +similar in spirit to the present version, but may differ in detail to address +new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies that a certain numbered version of the GNU General Public License +"or any later version" applies to it, you have the option of following the +terms and conditions either of that numbered version or of any later version +published by the Free Software Foundation. If the Program does not specify a +version number of the GNU General Public License, you may choose any version +ever published by the Free Software Foundation. + +If the Program specifies that a proxy can decide which future versions of the +GNU General Public License can be used, that proxy's public statement of +acceptance of a version permanently authorizes you to choose that version for +the Program. + +Later license versions may give you additional or different permissions. +However, no additional obligations are imposed on any author or copyright +holder as a result of your choosing to follow a later version. + +15. Disclaimer of Warranty. + +THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE +LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR +OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, +EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE +ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. +SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY +SERVICING, REPAIR OR CORRECTION. + +16. Limitation of Liability. + +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL +ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE +PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE +OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR +DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR +A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH +HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + +17. Interpretation of Sections 15 and 16. + +If the disclaimer of warranty and limitation of liability provided above +cannot be given local legal effect according to their terms, reviewing courts +shall apply local law that most closely approximates an absolute waiver of +all civil liability in connection with the Program, unless a warranty or +assumption of liability accompanies a copy of the Program in return for a +fee. + +END OF TERMS AND CONDITIONS +How to Apply These Terms to Your New Programs + +If you develop a new program, and you want it to be of the greatest possible +use to the public, the best way to achieve this is to make it free software +which everyone can redistribute and change under these terms. + +To do so, attach the following notices to the program. It is safest to attach +them to the start of each source file to most effectively state the exclusion +of warranty; and each file should have at least the "copyright" line and a +pointer to where the full notice is found. + + <one line to give the program's name and a brief idea of what it does.> + Copyright (C) <year> <name of author> + + 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 3 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, see <https://www.gnu.org/licenses/>. + +Also add information on how to contact you by electronic and paper mail. + +If the program does terminal interaction, make it output a short notice like +this when it starts in an interactive mode: + + <program> Copyright (C) <year> <name of author> + This program comes with ABSOLUTELY NO WARRANTY; for details type `show +w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, your program's commands might +be different; for a GUI interface, you would use an "about box". + +You should also get your employer (if you work as a programmer) or school, if +any, to sign a "copyright disclaimer" for the program, if necessary. For more +information on this, and how to apply and follow the GNU GPL, see +<https://www.gnu.org/licenses/>. + +The GNU General Public License does not permit incorporating your program +into proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Lesser General Public +License instead of this License. But first, please read +<https://www.gnu.org/licenses/why-not-lgpl.html>. + +______________ + +COPYING file last revised: July 22, 2022 diff --git a/doc/ReadMe-OS2.txt b/doc/ReadMe-OS2.txt new file mode 100644 index 00000000..8a9dc31c --- /dev/null +++ b/doc/ReadMe-OS2.txt @@ -0,0 +1,149 @@ + +VirtualBox for OS/2 OSE Edition ALPHA +===================================== + +Version 1.5.51_OSE_27858 + +03.02.2008 + + +This is an early development build of VirtualBox OSE Edition for OS/2. +Please backup your data and don't expect everything to be highly polished +and tuned just yet. If you find a *new* problem, meaning something +not listed below, please report it at http://forums.virtualbox.org. + +This package is an official unofficial build of VirtualBox for OS/2. +It means that it is coordinated by volunteers from Sun Microsystems that +are still in touch with OS/2 and keep patching VirtualBox at their spare +time to make sure it runs and more or less works under OS/2. + +PLEASE NOTE THAT THE OS/2 HOST (AND THEREFORE THE OS/2 VERSION OF +VIRTUALBOX) IS NOT OFFICIALLY SUPPORTED BY SUN MICROSYSTEMS! DO NOT +CONTACT SUN MICROSYSTEMS REGARDING THE OS/2 VERSION OF VIRTUALBOX NO +MATTER WHAT YOUR QUESTION IS ABOUT! THANK YOU FOR UNDERSTANDING. + + +Current Issues / TODOs +---------------------- + +* FE/Qt (Qt GUI frontend): + + - Mouse pointer shape in mouse integration mode. + - NumLock/ScrollLock synchronization. + - Seamless mode (no top-level window transparency on OS/2). + - Keyboard driver to intercept system key combinations + (Alt+Tab etc.) + +* Devices: + + - Host Floppy/DVD. + - Audio. + - Host interface networking. + - Internal networking. + - USB proxying. + +* Misc: + + - Shared clipboard. + - Starting more than one VM simultaneously. + - Installer. + - VMX support. + - VBoxSDL (resizing/scaling/keyboard/slowness). + - Very slow Resume after Pause in real mode guest applications. + +Also, please pay attention to the section called "OS/2 Specific Features" +below. + + +How to "Install" and Run +------------------------ + +1. Unpack this archive somewhere. + +2. Make sure you have a dot (.) in your LIBPATH statement in CONFIG.SYS. + +3. Put the following line at the beginning of your CONFIG.SYS + and reboot: + + DEVICE=<somewhere>\VBoxDrv.sys + +4. Go to <somewhere> and run VirtualBox.exe (Qt GUI frontend). + +5. Note that by default VirtualBox stores all user data in the + %HOME%\.VirtualBox directory. If %HOME% is not set, it will use + the <boot_drive>:\.VirtualBox directory. In either case, you may + overwrite the location of this directory using the VBOX_USER_HOME + environment variable. + +6. For best performance, it is recommended to install the VirtualBox + Guest Additions to the guest OS. The archive containing the ISO + image with Guest Additions for supported guest OSes (Windows, + Linux, OS/2) is named + + VBoxGuestAdditions_XXXXX.zip + + where XXXXX is the version number (it's best if it matches the version + number of this VirtualBox package). + + Download this ZIP from the same location you took this archive from + and unpack the contents to the directory containing VirtualBox.exe. + After that, you can mount the Additions ISO in the Qt GUI by selecting + Devices -> Install Guest Additions... from the menu. + + +Documentation and Support +------------------------- + +Please visit http://www.virtualbox.org where you can find a lot of useful +information about VirtualBox. There is a Community section where you can +try to request some help from other OS/2 users of VirtualBox. + +You can download the User Manual for the latest official release of +VirtualBox using this URL: + + http://www.virtualbox.org/download/UserManual.pdf + + +OS/2 Specific Features +---------------------- + +This section describes the features that are specific to the OS/2 version +of VirtualBox and may be absent in versions for other platforms. + +1. System key combinations such as Alt+Tab, Ctrl+Esc are currently always + grabbed by the host and never reach the guest even when the keyboard + is captured. In order to send these combinations to the guest OS, use + the following shortcuts (where Host is the host key defined in the + global settings dialog): + + Host+` (Tilde/Backquote) => Ctrl+Esc + Host+1 => Alt+Tab + Host+2 => Alt+Shift+Tab + +2. If you use two or more keyboard layouts on the OS/2 host (e.g. English + and Russian), make sure that the keyboard is switched to the English + layer when you work in the VirtualBox VM console window. Otherwise, some + shortcuts that involve the Host key (in particluar, all Host+<latin_letter> + shortcuts like Host+Q) may not work. Please note that the guest keyboard + layout has nothing to do with the host layout so you will still be able to + switch layouts in the guest using its own means. + +3. Make sure you do not do 'set LIBPATHSTRICT=T' in the environment you start + VirtualBox from: it will make the VirtualBox keyboard hook screw up your + host desktop (a workaround is to be found). + + +History of Changes +------------------ + +* 03.02.2008 + + - Initial release. + +* XX.XX.XXXX + + - Fixed: VirtualBox would hang or crash frequently on SMP machines in + ACPI mode. + + - Fixed: VBoxSDL keyboard key event to scan code conversion [contributed + by Paul Smedley]. diff --git a/doc/ReadMe-Solaris.txt b/doc/ReadMe-Solaris.txt new file mode 100644 index 00000000..024745cc --- /dev/null +++ b/doc/ReadMe-Solaris.txt @@ -0,0 +1,47 @@ + +@VBOX_PRODUCT@ for Oracle Solaris (TM) Operating System +-------------------------------------------------------- + +Upgrading: +---------- + +If you have an existing VirtualBox installation and you are upgrading to +a newer version of VirtualBox, please uninstall the previous version +before installing a newer one. Please refer to the "Uninstalling" section +at the end of this document for details. + + +Installing: +----------- + +After extracting the contents of the tar.gz file perform the following steps: + +1. Login as root using the "su" command. + +2. Install the VirtualBox package: + + pkgadd -d VirtualBox-@VBOX_VERSION_STRING@-SunOS-@KBUILD_TARGET_ARCH@-r@VBOX_SVN_REV@.pkg + + To perform an unattended (non-interactive) installation of this + package, add "-n -a autoresponse SUNWvbox" (without quotes) + to the end of the above pkgadd command. + +3. For each package, the installer will ask you to "Select package(s) you + wish to process". In response, type "1". + +4. Type "y" when asked about continuing the installation. + +At this point, all the required files should be installed on your system. +You can launch VirtualBox by running 'VirtualBox' from the terminal. + + +Uninstalling: +------------- + +To remove VirtualBox from your system, perform the following steps: + +1. Login as root using the "su" command. + +2. To remove VirtualBox, run the command: + pkgrm SUNWvbox + diff --git a/doc/ReadMe-Solaris11.txt b/doc/ReadMe-Solaris11.txt new file mode 100644 index 00000000..7440b265 --- /dev/null +++ b/doc/ReadMe-Solaris11.txt @@ -0,0 +1,55 @@ + +@VBOX_PRODUCT@ for Oracle Solaris 11 (TM) Operating System +---------------------------------------------------------------- + +Installing: +----------- + +After extracting the contents of the tar.xz file install the VirtualBox +package with the following command: + + $ sudo pkg install -g VirtualBox-@VBOX_VERSION_STRING@-SunOS-@KBUILD_TARGET_ARCH@-r@VBOX_SVN_REV@.p5p virtualbox + +Of course you can add options for performing the install in a different boot +environment or in a separate Solaris install. + +Normally you need to reboot the system to load the drivers which have been +added by the VirtualBox package. + +If you want to have VirtualBox immediately usable on your system you can run +the script /opt/VirtualBox/ipsinstall.sh which sets up everything immediately. + +At this point, all the required files should be installed on your system. +You can launch VirtualBox by running 'VirtualBox' from the terminal. + + +Upgrading: +---------- + +If you want to upgrade from an older to a newer version of the VirtualBox IPS +package you can use the following command after extracting the contents of the +tar.xz file: + + $ sudo pkg update -g VirtualBox-@VBOX_VERSION_STRING@-SunOS-@KBUILD_TARGET_ARCH@-r@VBOX_SVN_REV@.p5p virtualbox + +If you want to upgrade from the SysV package of VirtualBox to the IPS one, +please uninstall the previous package before installing the IPS one. Please +refer to the "Uninstalling" and "Installing" sections of this document for +details. + +It is your responsibility to ensure that no VirtualBox VMs or other related +activities are running. One possible way is using the command pgrep VBoxSVC. If +this shows no output then it is safe to upgrade VirtualBox. + + +Uninstalling: +------------- + +To remove VirtualBox from your system, run the following command: + + $ sudo pkg uninstall virtualbox + +It is your responsibility to ensure that no VirtualBox VMs or other related +activities are running. One possible way is using the command pgrep VBoxSVC. If +this shows no output then it is safe to uninstall VirtualBox. + diff --git a/doc/VBox-CodingGuidelines.cpp b/doc/VBox-CodingGuidelines.cpp new file mode 100644 index 00000000..1cca87d9 --- /dev/null +++ b/doc/VBox-CodingGuidelines.cpp @@ -0,0 +1,1031 @@ +/* $Id: VBox-CodingGuidelines.cpp $ */ +/** @file + * VBox - Coding Guidelines. + */ + +/* + * Copyright (C) 2006-2023 Oracle and/or its affiliates. + * + * This file is part of VirtualBox base platform packages, as + * available from https://www.virtualbox.org. + * + * 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, in version 3 of the + * License. + * + * 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, see <https://www.gnu.org/licenses>. + * + * SPDX-License-Identifier: GPL-3.0-only + */ + +/** @page pg_vbox_guideline VBox Coding Guidelines + * + * The compulsory sections of these guidelines are to be followed in all of the + * VBox sources. Please note that local guidelines in parts of the VBox source + * tree may promote the optional ones to compulsory status. The VBox tree also + * contains some 3rd party sources where it is good to follow the local coding + * style while keeping these guidelines in mind. + * + * Contents: + * - @ref sec_vbox_guideline_compulsory + * - @ref sec_vbox_guideline_compulsory_sub64 + * - @ref sec_vbox_guideline_compulsory_cppmain + * - @ref sec_vbox_guideline_compulsory_cppqtgui + * - @ref sec_vbox_guideline_compulsory_xslt + * - @ref sec_vbox_guideline_compulsory_doxygen + * - @ref sec_vbox_guideline_compulsory_guest + * - @ref sec_vbox_guideline_optional + * - @ref sec_vbox_guideline_optional_layout + * - @ref sec_vbox_guideline_optional_prefix + * - @ref sec_vbox_guideline_optional_misc + * - @ref sec_vbox_guideline_warnings + * - @ref sec_vbox_guideline_warnings_signed_unsigned_compare + * - @ref sec_vbox_guideline_svn + * + * Local guidelines overrides: + * - src/VBox/VMM/: @ref pg_vmm_guideline (src/VBox/VMM/Docs-CodingGuidelines.cpp) + * - src/VBox/ValidationKit/: @ref pg_validationkit_guideline (src/VBox/ValidationKit/ValidationKitCodingGuidelines.cpp) + * - src/VBox/Runtime/: All of @ref sec_vbox_guideline_optional is mandatory. + * - src/VBox/Main/: @ref sec_vbox_guideline_compulsory_cppmain + * - src/VBox/Frontends/VirtualBox/: @ref sec_vbox_guideline_compulsory_cppqtgui + * + * + * @section sec_vbox_guideline_compulsory Compulsory + * + * <ul> + * + * <li> The indentation size is 4 chars. + * + * <li> Tabs are only ever used in makefiles. + * + * <li> Use RT and VBOX types. + * + * <li> Use Runtime functions. + * + * <li> Use the standard bool, uintptr_t, intptr_t and [u]int[1-9+]_t types. + * + * <li> Avoid using plain unsigned and int. + * + * <li> Use static wherever possible. This makes the namespace less polluted + * and avoids nasty name clash problems which can occur, especially on + * Unix-like systems. (1) It also simplifies locating callers when + * changing it (single source file vs entire VBox tree). + * + * <li> Public names are of the form Domain[Subdomain[]]Method, using mixed + * casing to mark the words. The main domain is all uppercase. + * (Think like java, mapping domain and subdomain to packages/classes.) + * + * <li> Public names are always declared using the appropriate DECL macro. (2) + * + * <li> Internal names starts with a lowercased main domain. + * + * <li> Defines are all uppercase and separate words with underscore. + * This applies to enum values too. + * + * <li> Typedefs are all uppercase and contain no underscores to distinguish + * them from defines. Alternatively, all uppercase, separate words with + * underscores and ending with '_T'. The latter is not allowed in IPRT. + * + * <li> Pointer typedefs start with 'P'. If pointer to const then 'PC'. + * + * <li> Function typedefs start with 'FN'. If pointer to FN then 'PFN'. + * + * <li> All files are case sensitive. + * + * <li> Slashes are unix slashes ('/') runtime converts when necessary. + * + * <li> char strings are UTF-8. + * + * <li> Strings from any external source must be treated with utmost care as + * they do not have to be valid UTF-8. Only trust internal strings. + * + * <li> All functions return VBox status codes. There are three general + * exceptions from this: + * + * <ol> + * <li>Predicate functions. These are function which are boolean in + * nature and usage. They return bool. The function name will + * include 'Has', 'Is' or similar. + * <li>Functions which by nature cannot possibly fail. + * These return void. + * <li>"Get"-functions which return what they ask for. + * A get function becomes a "Query" function if there is any + * doubt about getting what is ask for. + * </ol> + * + * <li> VBox status codes have three subdivisions: + * <ol> + * <li> Errors, which are VERR_ prefixed and negative. + * <li> Warnings, which are VWRN_ prefixed and positive. + * <li> Informational, which are VINF_ prefixed and positive. + * </ol> + * + * <li> Platform/OS operation are generalized and put in the IPRT. + * + * <li> Other useful constructs are also put in the IPRT. + * + * <li> The code shall not cause compiler warnings. Check this on ALL + * the platforms. + * + * <li> The use of symbols leading with single or double underscores is + * forbidden as that intrudes on reserved compiler/system namespace. (3) + * + * <li> All files have file headers with $Id and a file tag which describes + * the file in a sentence or two. + * Note: Use the svn-ps.cmd/svn-ps.sh utility with the -a option to add + * new sources with keyword expansion and exporting correctly + * configured. + * + * <li> All public functions are fully documented in Doxygen style using the + * javadoc dialect (using the 'at' instead of the 'slash' as + * commandprefix.) + * + * <li> All structures in header files are described, including all their + * members. (Doxygen style, of course.) + * + * <li> All modules have a documentation '\@page' in the main source file + * which describes the intent and actual implementation. + * + * <li> Code which is doing things that are not immediately comprehensible + * shall include explanatory comments. + * + * <li> Documentation and comments are kept up to date. + * + * <li> Headers in /include/VBox shall not contain any slash-slash C++ + * comments, only ANSI C comments! + * + * <li> Comments on \#else indicates what begins while the comment on a + * \#endif indicates what ended. Only add these when there are more than + * a few lines (6-10) of \#ifdef'ed code, otherwise they're just clutter. + * + * <li> \#ifdefs around a single function shall be tight, i.e. no empty + * lines between it and the function documentation and body. + * + * <li> \#ifdefs around more than one function shall be relaxed, i.e. leave at + * least one line before the first function's documentation comment and + * one line after the end of the last function. + * + * <li> No 'else' after if block ending with 'return', 'break', or 'continue'. + * + * <li> The term 'last' is inclusive, whereas the term 'end' is exclusive. + * + * <li> Go through all of this: https://www.slideshare.net/olvemaudal/deep-c/ + * + * <li> Avoid throwing exceptions, always prefer returning statuses. + * Crappy exception handling is rewared by a glass of water in the face. + * + * </ul> + * + * (1) It is common practice on Unix to have a single symbol namespace for an + * entire process. If one is careless symbols might be resolved in a + * different way that one expects, leading to weird problems. + * + * (2) This is common practice among most projects dealing with modules in + * shared libraries. The Windows / PE __declspect(import) and + * __declspect(export) constructs are the main reason for this. + * OTOH, we do perhaps have a bit too detailed graining of this in VMM... + * + * (3) There are guys out there grepping public sources for symbols leading with + * single and double underscores as well as gotos and other things + * considered bad practice. They'll post statistics on how bad our sources + * are on some mailing list, forum or similar. + * + * + * @subsection sec_vbox_guideline_compulsory_sub64 64-bit and 32-bit + * + * Here are some amendments which address 64-bit vs. 32-bit portability issues. + * + * Some facts first: + * + * <ul> + * + * <li> On 64-bit Windows the type long remains 32-bit. On nearly all other + * 64-bit platforms long is 64-bit. + * + * <li> On all 64-bit platforms we care about, int is 32-bit, short is 16 bit + * and char is 8-bit. + * (I don't know about any platforms yet where this isn't true.) + * + * <li> size_t, ssize_t, uintptr_t, ptrdiff_t and similar are all 64-bit on + * 64-bit platforms. (These are 32-bit on 32-bit platforms.) + * + * <li> There is no inline assembly support in the 64-bit Microsoft compilers. + * + * </ul> + * + * Now for the guidelines: + * + * <ul> + * + * <li> Never, ever, use int, long, ULONG, LONG, DWORD or similar to cast a + * pointer to integer. Use uintptr_t or intptr_t. If you have to use + * NT/Windows types, there is the choice of ULONG_PTR and DWORD_PTR. + * + * <li> Avoid where ever possible the use of the types 'long' and 'unsigned + * long' as these differs in size between windows and the other hosts + * (see above). + * + * <li> RT_OS_WINDOWS is defined to indicate Windows. Do not use __WIN32__, + * __WIN64__ and __WIN__ because they are all deprecated and scheduled + * for removal (if not removed already). Do not use the compiler + * defined _WIN32, _WIN64, or similar either. The bitness can be + * determined by testing ARCH_BITS. + * Example: + * @code + * #ifdef RT_OS_WINDOWS + * // call win32/64 api. + * #endif + * #ifdef RT_OS_WINDOWS + * # if ARCH_BITS == 64 + * // call win64 api. + * # else // ARCH_BITS == 32 + * // call win32 api. + * # endif // ARCH_BITS == 32 + * #else // !RT_OS_WINDOWS + * // call posix api + * #endif // !RT_OS_WINDOWS + * @endcode + * + * <li> There are RT_OS_xxx defines for each OS, just like RT_OS_WINDOWS + * mentioned above. Use these defines instead of any predefined + * compiler stuff or defines from system headers. + * + * <li> RT_ARCH_X86 is defined when compiling for the x86 the architecture. + * Do not use __x86__, __X86__, __[Ii]386__, __[Ii]586__, or similar + * for this purpose. + * + * <li> RT_ARCH_AMD64 is defined when compiling for the AMD64 architecture. + * Do not use __AMD64__, __amd64__ or __x64_86__. + * + * <li> Take care and use size_t when you have to, esp. when passing a pointer + * to a size_t as a parameter. + * + * <li> Be wary of type promotion to (signed) integer. For example the + * following will cause u8 to be promoted to int in the shift, and then + * sign extended in the assignment 64-bit: + * @code + * uint8_t u8 = 0xfe; + * uint64_t u64 = u8 << 24; + * // u64 == 0xfffffffffe000000 + * @endcode + * + * </ul> + * + * @subsubsection sec_vbox_guideline_compulsory_sub64_comp Comparing the GCC and MSC calling conventions + * + * GCC expects the following (cut & past from page 20 in the ABI draft 0.96): + * + * @verbatim + %rax temporary register; with variable arguments passes information about the + number of SSE registers used; 1st return register. + [Not preserved] + %rbx callee-saved register; optionally used as base pointer. + [Preserved] + %rcx used to pass 4th integer argument to functions. + [Not preserved] + %rdx used to pass 3rd argument to functions; 2nd return register + [Not preserved] + %rsp stack pointer + [Preserved] + %rbp callee-saved register; optionally used as frame pointer + [Preserved] + %rsi used to pass 2nd argument to functions + [Not preserved] + %rdi used to pass 1st argument to functions + [Not preserved] + %r8 used to pass 5th argument to functions + [Not preserved] + %r9 used to pass 6th argument to functions + [Not preserved] + %r10 temporary register, used for passing a function's static chain + pointer [Not preserved] + %r11 temporary register + [Not preserved] + %r12-r15 callee-saved registers + [Preserved] + %xmm0-%xmm1 used to pass and return floating point arguments + [Not preserved] + %xmm2-%xmm7 used to pass floating point arguments + [Not preserved] + %xmm8-%xmm15 temporary registers + [Not preserved] + %mmx0-%mmx7 temporary registers + [Not preserved] + %st0 temporary register; used to return long double arguments + [Not preserved] + %st1 temporary registers; used to return long double arguments + [Not preserved] + %st2-%st7 temporary registers + [Not preserved] + %fs Reserved for system use (as thread specific data register) + [Not preserved] + @endverbatim + * + * Direction flag is preserved as cleared. + * The stack must be aligned on a 16-byte boundary before the 'call/jmp' instruction. + * + * MSC expects the following: + * @verbatim + rax return value, not preserved. + rbx preserved. + rcx 1st argument, integer, not preserved. + rdx 2nd argument, integer, not preserved. + rbp preserved. + rsp preserved. + rsi preserved. + rdi preserved. + r8 3rd argument, integer, not preserved. + r9 4th argument, integer, not preserved. + r10 scratch register, not preserved. + r11 scratch register, not preserved. + r12-r15 preserved. + xmm0 1st argument, fp, return value, not preserved. + xmm1 2st argument, fp, not preserved. + xmm2 3st argument, fp, not preserved. + xmm3 4st argument, fp, not preserved. + xmm4-xmm5 scratch, not preserved. + xmm6-xmm15 preserved. + @endverbatim + * + * Dunno what the direction flag is... + * The stack must be aligned on a 16-byte boundary before the 'call/jmp' instruction. + * + * + * @subsection sec_vbox_guideline_compulsory_cppmain C++ guidelines for Main + * + * Since the Main API code is a large amount of C++ code, it is allowed but + * not required to use C++ style comments (as permanent comments, beyond the + * temporary use allowed by the general coding guideline). This is a weak + * preference, i.e. large scale comment style changes are not encouraged. + * + * Main is currently (2009) full of hard-to-maintain code that uses complicated + * templates. The new mid-term goal for Main is to have less custom templates + * instead of more for the following reasons: + * + * <ul> + * + * <li> Template code is harder to read and understand. Custom templates create + * territories which only the code writer understands. + * + * <li> Errors in using templates create terrible C++ compiler messages. + * + * <li> Template code is really hard to look at in a debugger. + * + * <li> Templates slow down the compiler a lot. + * + * </ul> + * + * In particular, the following bits should be considered deprecated and should + * NOT be used in new code: + * + * <ul> + * + * <li> everything in include/iprt/cpputils.h (auto_ref_ptr, exception_trap_base, + * char_auto_ptr and friends) + * + * </ul> + * + * Generally, in many cases, a simple class with a proper destructor can achieve + * the same effect as a 1,000-line template include file, and the code is + * much more accessible that way. + * + * Using standard STL templates like std::list, std::vector and std::map is OK. + * Exceptions are: + * + * <ul> + * + * <li> Guest Additions because we don't want to link against libstdc++ there. + * + * <li> std::string should not be used because we have iprt::MiniString and + * com::Utf8Str which can convert efficiently with COM's UTF-16 strings. + * + * <li> std::auto_ptr<> in general; that part of the C++ standard is just broken. + * Write a destructor that calls delete. + * + * </ul> + * + * @subsection sec_vbox_guideline_compulsory_cppqtgui C++ guidelines for the Qt GUI + * + * The Qt GUI is currently (2010) on its way to become more compatible to the + * rest of VirtualBox coding style wise. From now on, all the coding style + * rules described in this file are also mandatory for the Qt GUI. Additionally + * the following rules should be respected: + * + * <ul> + * + * <li> GUI classes which correspond to GUI tasks should be prefixed by UI (no VBox anymore) + * + * <li> Classes which extents some of the Qt classes should be prefix by QI + * + * <li> General task classes should be prefixed by C + * + * <li> Slots are prefixed by slt -> sltName + * + * <li> Signals are prefixed by sig -> sigName + * + * <li> Use Qt classes for lists, strings and so on, the use of STL classes should + * be avoided + * + * <li> All files like .cpp, .h, .ui, which belong together are located in the + * same directory and named the same + * + * </ul> + * + * + * @subsection sec_vbox_guideline_compulsory_xslt XSLT + * + * XSLT (eXtensible Stylesheet Language Transformations) is used quite a bit in + * the Main API area of VirtualBox to generate sources and bindings to that API. + * There are a couple of common pitfalls worth mentioning: + * + * <ul> + * + * <li> Never do repeated //interface[\@name=...] and //enum[\@name=...] lookups + * because they are expensive. Instead delcare xsl:key elements for these + * searches and do the lookup using the key() function. xsltproc uses + * (per current document) hash tables for each xsl:key, i.e. very fast. + * + * <li> When output type is 'text' make sure to call xsltprocNewlineOutputHack + * from typemap-shared.inc.xsl every few KB of output, or xsltproc will + * end up wasting all the time reallocating the output buffer. + * + * </ul> + * + * + * @subsection sec_vbox_guideline_compulsory_doxygen Doxygen Comments + * + * As mentioned above, we shall use doxygen/javadoc style commenting of public + * functions, typedefs, classes and such. It is mandatory to use this style + * everywhere! + * + * A couple of hints on how to best write doxygen comments: + * + * <ul> + * + * <li> A good class, method, function, structure or enum doxygen comment + * starts with a one line sentence giving a brief description of the + * item. Details comes in a new paragraph (after blank line). + * + * <li> Except for list generators like \@todo, \@cfgm, \@gcfgm and others, + * all doxygen comments are related to things in the code. So, for + * instance you DO NOT add a doxygen \@note comment in the middle of a + * because you've got something important to note, you add a normal + * comment like 'Note! blah, very importan blah!' + * + * <li> We do NOT use TODO/XXX/BUGBUG or similar markers in the code to flag + * things needing fixing later, we always use \@todo doxygen comments. + * + * <li> There is no colon after the \@todo. And it is ALWAYS in a doxygen + * comment. + * + * <li> The \@retval tag is used to explain status codes a method/function may + * returns. It is not used to describe output parameters, that is done + * using the \@param or \@param[out] tag. + * + * </ul> + * + * See https://www.stack.nl/~dimitri/doxygen/manual/index.html for the official + * doxygen documention. + * + * + * + * @subsection sec_vbox_guideline_compulsory_guest Handling of guest input + * + * First, guest input should ALWAYS be consider to be TOXIC and constructed with + * MALICIOUS intent! Max paranoia level! + * + * Second, when getting inputs from memory shared with the guest, be EXTREMELY + * careful to not re-read input from shared memory after validating it, because + * that will create TOCTOU problems. So, after reading input from shared memory + * always use the RT_UNTRUSTED_NONVOLATILE_COPY_FENCE() macro. For more details + * on TOCTOU: https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use + * + * Thirdly, considering the recent speculation side channel issues, spectre v1 + * in particular, we would like to be ready for future screwups. This means + * having input validation in a separate block of code that ends with one (or + * more) RT_UNTRUSTED_VALIDATED_FENCE(). + * + * So the rules: + * + * <ul> + * + * <li> Mark all pointers to shared memory with RT_UNTRUSTED_VOLATILE_GUEST. + * + * <li> Copy volatile data into local variables or heap before validating + * them (see RT_COPY_VOLATILE() and RT_BCOPY_VOLATILE(). + * + * <li> Place RT_UNTRUSTED_NONVOLATILE_COPY_FENCE() after a block copying + * volatile data. + * + * <li> Always validate untrusted inputs in a block ending with a + * RT_UNTRUSTED_VALIDATED_FENCE(). + * + * <li> Use the ASSERT_GUEST_XXXX macros from VBox/AssertGuest.h to validate + * guest input. (Do NOT use iprt/assert.h macros.) + * + * <li> Validation of an input B may require using another input A to look up + * some data, in which case its necessary to insert an + * RT_UNTRUSTED_VALIDATED_FENCE() after validating A and before A is used + * for the lookup. + * + * For example A is a view identifier, idView, and B is an offset into + * the view's framebuffer area, offView. To validate offView (B) it is + * necessary to get the size of the views framebuffer region: + * @code + * uint32_t const idView = pReq->idView; // A + * uint32_t const offView = pReq->offView; // B + * RT_UNTRUSTED_NONVOLATILE_COPY_FENCE(); + * + * ASSERT_GUEST_RETURN(idView < pThis->cView, + * VERR_INVALID_PARAMETER); + * RT_UNTRUSTED_VALIDATED_FENCE(); + * const MYVIEW *pView = &pThis->aViews[idView]; + * ASSERT_GUEST_RETURN(offView < pView->cbFramebufferArea, + * VERR_OUT_OF_RANGE); + * RT_UNTRUSTED_VALIDATED_FENCE(); + * @endcode + * + * <li> Take care to make sure input check are not subject to integer overflow problems. + * + * For instance when validating an area, you must not just add cbDst + offDst + * and check against pThis->offEnd or something like that. Rather do: + * @code + * uint32_t const offDst = pReq->offDst; + * uint32_t const cbDst = pReq->cbDst; + * RT_UNTRUSTED_NONVOLATILE_COPY_FENCE(); + * + * ASSERT_GUEST_RETURN( cbDst <= pThis->cbSrc + * && offDst < pThis->cbSrc - cbDst, + * VERR_OUT_OF_RANGE); + * RT_UNTRUSTED_VALIDATED_FENCE(); + * @endcode + * + * <li> Input validation does not only apply to shared data cases, but also to + * I/O port and MMIO handlers. + * + * <li> Ditto for kernel drivers working with usermode inputs. + * + * </ul> + * + * + * Problem patterns: + * - https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use + * - https://googleprojectzero.blogspot.de/2018/01/reading-privileged-memory-with-side.html + * (Variant 1 only). + * - https://en.wikipedia.org/wiki/Integer_overflow + * + * + * + * @section sec_vbox_guideline_optional Optional + * + * First part is the actual coding style and all the prefixes. The second part + * is a bunch of good advice. + * + * + * @subsection sec_vbox_guideline_optional_layout The code layout + * + * <ul> + * + * <li> Max line length is 130 chars. Exceptions are table-like + * code/initializers and Log*() statements (don't waste unnecessary + * vertical space on debug logging). + * + * <li> Comments should try stay within the usual 80 columns as these are + * denser and too long lines may be harder to read. + * + * <li> Curly brackets are not indented. Example: + * @code + * if (true) + * { + * Something1(); + * Something2(); + * } + * else + * { + * SomethingElse1(). + * SomethingElse2(). + * } + * @endcode + * + * <li> Space before the parentheses when it comes after a C keyword. + * + * <li> No space between argument and parentheses. Exception for complex + * expression. Example: + * @code + * if (PATMR3IsPatchGCAddr(pVM, GCPtr)) + * @endcode + * + * <li> The else of an if is always the first statement on a line. (No curly + * stuff before it!) + * + * <li> else and if go on the same line if no { compound statement } + * follows the if. Example: + * @code + * if (fFlags & MYFLAGS_1) + * fFlags &= ~MYFLAGS_10; + * else if (fFlags & MYFLAGS_2) + * { + * fFlags &= ~MYFLAGS_MASK; + * fFlags |= MYFLAGS_5; + * } + * else if (fFlags & MYFLAGS_3) + * @endcode + * + * <li> Slightly complex boolean expressions are split into multiple lines, + * putting the operators first on the line and indenting it all according + * to the nesting of the expression. The purpose is to make it as easy as + * possible to read. Example: + * @code + * if ( RT_SUCCESS(rc) + * || (fFlags & SOME_FLAG)) + * @endcode + * + * <li> When 'if' or 'while' statements gets long, the closing parentheses + * goes right below the opening parentheses. This may be applied to + * sub-expression. Example: + * @code + * if ( RT_SUCCESS(rc) + * || ( fSomeStuff + * && fSomeOtherStuff + * && fEvenMoreStuff + * ) + * || SomePredicateFunction() + * ) + * { + * ... + * } + * @endcode + * + * <li> The case is indented from the switch (to avoid having the braces for + * the 'case' at the same level as the 'switch' statement). + * + * <li> If a case needs curly brackets they contain the entire case, are not + * indented from the case, and the break or return is placed inside them. + * Example: + * @code + * switch (pCur->eType) + * { + * case PGMMAPPINGTYPE_PAGETABLES: + * { + * unsigned iPDE = pCur->GCPtr >> PGDIR_SHIFT; + * unsigned iPT = (pCur->GCPtrEnd - pCur->GCPtr) >> PGDIR_SHIFT; + * while (iPT-- > 0) + * if (pPD->a[iPDE + iPT].n.u1Present) + * return VERR_HYPERVISOR_CONFLICT; + * break; + * } + * } + * @endcode + * + * <li> In a do while construction, the while is on the same line as the + * closing "}" if any are used. + * Example: + * @code + * do + * { + * stuff; + * i--; + * } while (i > 0); + * @endcode + * + * <li> Comments are in C style. C++ style comments are used for temporary + * disabling a few lines of code. + * + * <li> No unnecessary parentheses in expressions (just don't over do this + * so that gcc / msc starts bitching). Find a correct C/C++ operator + * precedence table if needed. + * + * <li> 'for (;;)' is preferred over 'while (true)' and 'while (1)'. + * + * <li> Parameters are indented to the start parentheses when breaking up + * function calls, declarations or prototypes. (This is in line with + * how 'if', 'for' and 'while' statements are done as well.) Example: + * @code + * RTPROCESS hProcess; + * int rc = RTProcCreateEx(papszArgs[0], + * papszArgs, + * RTENV_DEFAULT, + * fFlags, + * NULL, // phStdIn + * NULL, // phStdOut + * NULL, // phStdErr + * NULL, // pszAsUser + * NULL, // pszPassword + * NULL, // pExtraData + * &hProcess); + * @endcode + * + * <li> That Dijkstra is dead is no excuse for using gotos. + * + * <li> Using do-while-false loops to avoid gotos is considered very bad form. + * They create hard to read code. They tend to be either too short (i.e. + * pointless) or way to long (split up the function already), making + * tracking the state is difficult and prone to bugs. Also, they cause + * the compiler to generate suboptimal code, because the break branches + * are by preferred over the main code flow (MSC has no branch hinting!). + * Instead, do make use the 130 columns (i.e. nested ifs) and split + * the code up into more functions! + * + * <li> Avoid code like + * @code + * int foo; + * int rc; + * ... + * rc = FooBar(); + * if (RT_SUCCESS(rc)) + * { + * foo = getFoo(); + * ... + * pvBar = RTMemAlloc(sizeof(*pvBar)); + * if (!pvBar) + * rc = VERR_NO_MEMORY; + * } + * if (RT_SUCCESS(rc)) + * { + * buzz = foo; + * ... + * } + * @endcode + * The intention of such code is probably to save some horizontal space + * but unfortunately it's hard to read and the scope of certain varables + * (e.g. foo in this example) is not optimal. Better use the following + * style: + * @code + * int rc; + * ... + * rc = FooBar(); + * if (RT_SUCCESS(rc)) + * { + * int foo = getFoo(); + * ... + * pvBar = RTMemAlloc(sizeof(*pvBar)); + * if (pvBar) + * { + * buzz = foo; + * ... + * } + * else + * rc = VERR_NO_MEMORY; + * } + * @endcode + * + * </ul> + * + * @subsection sec_vbox_guideline_optional_prefix Variable / Member Prefixes + * + * Prefixes are meant to provide extra context clues to a variable/member, we + * therefore avoid using prefixes that just indicating the type if a better + * choice is available. + * + * + * The prefixes: + * + * <ul> + * + * <li> The 'g_' (or 'g') prefix means a global variable, either on file or module level. + * + * <li> The 's_' (or 's') prefix means a static variable inside a function or + * class. This is not used for static variables on file level, use 'g_' + * for those (logical, right). + * + * <li> The 'm_' (or 'm') prefix means a class data member. + * + * In new code in Main, use "m_" (and common sense). As an exception, + * in Main, if a class encapsulates its member variables in an anonymous + * structure which is declared in the class, but defined only in the + * implementation (like this: 'class X { struct Data; Data *m; }'), then + * the pointer to that struct is called 'm' itself and its members then + * need no prefix, because the members are accessed with 'm->member' + * already which is clear enough. + * + * <li> The 'a_' prefix means a parameter (argument) variable. This is + * sometimes written 'a' in parts of the source code that does not use + * the array prefix. + * + * <li> The 'p' prefix means pointer. For instance 'pVM' is pointer to VM. + * + * <li> The 'r' prefix means that something is passed by reference. + * + * <li> The 'k' prefix means that something is a constant. For instance + * 'enum { kStuff };'. This is usually not used in combination with + * 'p', 'r' or any such thing, it's main main use is to make enums + * easily identifiable. + * + * <li> The 'a' prefix means array. For instance 'aPages' could be read as + * array of pages. + * + * <li> The 'c' prefix means count. For instance 'cbBlock' could be read, + * count of bytes in block. (1) + * + * <li> The 'cx' prefix means width (count of 'x' units). + * + * <li> The 'cy' prefix means height (count of 'y' units). + * + * <li> The 'x', 'y' and 'z' prefix refers to the x-, y- , and z-axis + * respectively. + * + * <li> The 'off' prefix means offset. + * + * <li> The 'i' or 'idx' prefixes usually means index. Although the 'i' one + * can sometimes just mean signed integer. + * + * <li> The 'i[1-9]+' prefix means a fixed bit size variable. Frequently + * used with the int[1-9]+_t types where the width is really important. + * In most cases 'i' is more appropriate. [type] + * + * <li> The 'e' (or 'enm') prefix means enum. + * + * <li> The 'u' prefix usually means unsigned integer. Exceptions follows. + * + * <li> The 'u[1-9]+' prefix means a fixed bit size variable. Frequently + * used with the uint[1-9]+_t types and with bitfields where the width is + * really important. In most cases 'u' or 'b' (byte) would be more + * appropriate. [type] + * + * <li> The 'b' prefix means byte or bytes. [type] + * + * <li> The 'f' prefix means flags. Flags are unsigned integers of some kind + * or booleans. + * + * <li> TODO: need prefix for real float. [type] + * + * <li> The 'rd' prefix means real double and is used for 'double' variables. + * [type] + * + * <li> The 'lrd' prefix means long real double and is used for 'long double' + * variables. [type] + * + * <li> The 'ch' prefix means a char, the (signed) char type. [type] + * + * <li> The 'wc' prefix means a wide/windows char, the RTUTF16 type. [type] + * + * <li> The 'uc' prefix means a Unicode Code point, the RTUNICP type. [type] + * + * <li> The 'uch' prefix means unsigned char. It's rarely used. [type] + * + * <li> The 'sz' prefix means zero terminated character string (array of + * chars). (UTF-8) + * + * <li> The 'wsz' prefix means zero terminated wide/windows character string + * (array of RTUTF16). + * + * <li> The 'usz' prefix means zero terminated Unicode string (array of + * RTUNICP). + * + * <li> The 'str' prefix means C++ string; either a std::string or, in Main, + * a Utf8Str or, in Qt, a QString. When used with 'p', 'r', 'a' or 'c' + * the first letter should be capitalized. + * + * <li> The 'bstr' prefix, in Main, means a UTF-16 Bstr. When used with 'p', + * 'r', 'a' or 'c' the first letter should be capitalized. + * + * <li> The 'pfn' prefix means pointer to function. Common usage is 'pfnCallback' + * and such like. + * + * <li> The 'psz' prefix is a combination of 'p' and 'sz' and thus means + * pointer to a zero terminated character string. (UTF-8) + * + * <li> The 'pcsz' prefix is used to indicate constant string pointers in + * parts of the code. Most code uses 'psz' for const and non-const + * string pointers, so please ignore this one. + * + * <li> The 'l' prefix means (signed) long. We try avoid using this, + * expecially with the 'LONG' types in Main as these are not 'long' on + * 64-bit non-Windows platforms and can cause confusion. Alternatives: + * 'i' or 'i32'. [type] + * + * <li> The 'ul' prefix means unsigned long. We try avoid using this, + * expecially with the 'ULONG' types in Main as these are not 'unsigned + * long' on 64-bit non-Windows platforms and can cause confusion. + * Alternatives: 'u' or 'u32'. [type] + * + * </ul> + * + * (1) Except in the occasional 'pcsz' prefix, the 'c' prefix is never ever + * used in the meaning 'const'. + * + * + * @subsection sec_vbox_guideline_optional_misc Misc / Advice / Stuff + * + * <ul> + * + * <li> When writing code think as the reader. + * + * <li> When writing code think as the compiler. (2) + * + * <li> When reading code think as if it's full of bugs - find them and fix them. + * + * <li> Pointer within range tests like: + * @code + * if ((uintptr_t)pv >= (uintptr_t)pvBase && (uintptr_t)pv < (uintptr_t)pvBase + cbRange) + * @endcode + * Can also be written as (assuming cbRange unsigned): + * @code + * if ((uintptr_t)pv - (uintptr_t)pvBase < cbRange) + * @endcode + * Which is shorter and potentially faster. (1) + * + * <li> Avoid unnecessary casting. All pointers automatically cast down to + * void *, at least for non class instance pointers. + * + * <li> It's very very bad practise to write a function larger than a + * screen full (1024x768) without any comprehensibility and explaining + * comments. + * + * <li> More to come.... + * + * </ul> + * + * (1) Important, be very careful with the casting. In particular, note that + * a compiler might treat pointers as signed (IIRC). + * + * (2) "A really advanced hacker comes to understand the true inner workings of + * the machine - he sees through the language he's working in and glimpses + * the secret functioning of the binary code - becomes a Ba'al Shem of + * sorts." (Neal Stephenson "Snow Crash") + * + * + * + * @section sec_vbox_guideline_warnings Compiler Warnings + * + * The code should when possible compile on all platforms and compilers without any + * warnings. That's a nice idea, however, if it means making the code harder to read, + * less portable, unreliable or similar, the warning should not be fixed. + * + * Some of the warnings can seem kind of innocent at first glance. So, let's take the + * most common ones and explain them. + * + * + * @subsection sec_vbox_guideline_warnings_signed_unsigned_compare Signed / Unsigned Compare + * + * GCC says: "warning: comparison between signed and unsigned integer expressions" + * MSC says: "warning C4018: '<|<=|==|>=|>' : signed/unsigned mismatch" + * + * The following example will not output what you expect: +@code +#include <stdio.h> +int main() +{ + signed long a = -1; + unsigned long b = 2294967295; + if (a < b) + printf("%ld < %lu: true\n", a, b); + else + printf("%ld < %lu: false\n", a, b); + return 0; +} +@endcode + * If I understood it correctly, the compiler will convert a to an + * unsigned long before doing the compare. + * + * + * + * @section sec_vbox_guideline_svn Subversion Commit Rules + * + * + * Before checking in: + * + * <ul> + * + * <li> Check Tinderbox and make sure the tree is green across all platforms. If it's + * red on a platform, don't check in. If you want, warn in the \#vbox channel and + * help make the responsible person fix it. + * NEVER CHECK IN TO A BROKEN BUILD. + * + * <li> When checking in keep in mind that a commit is atomic and that the Tinderbox and + * developers are constantly checking out the tree. Therefore do not split up the + * commit unless it's into 100% independent parts. If you need to split it up in order + * to have sensible commit comments, make the sub-commits as rapid as possible. + * + * <li> If you make a user visible change, such as fixing a reported bug, + * make sure you add an entry to doc/manual/user_ChangeLogImpl.xml. + * + * <li> If you are adding files make sure set the right attributes. + * svn-ps.sh/cmd was created for this purpose, please make use of it. + * + * </ul> + * + * After checking in: + * + * <ul> + * + * <li> After checking-in, you watch Tinderbox until your check-ins clear. You do not + * go home. You do not sleep. You do not log out or experiment with drugs. You do + * not become unavailable. If you break the tree, add a comment saying that you're + * fixing it. If you can't fix it and need help, ask in the \#innotek channel or back + * out the change. + * + * </ul> + * + * (Inspired by mozilla tree rules.) + * + * + */ + diff --git a/doc/VBox-MakefileGuidelines.cpp b/doc/VBox-MakefileGuidelines.cpp new file mode 100644 index 00000000..51dced8d --- /dev/null +++ b/doc/VBox-MakefileGuidelines.cpp @@ -0,0 +1,216 @@ +/* $Id: VBox-MakefileGuidelines.cpp $ */ +/** @file + * VBox - Makefile Guidelines. + */ + +/* + * Copyright (C) 2009-2023 Oracle and/or its affiliates. + * + * This file is part of VirtualBox base platform packages, as + * available from https://www.virtualbox.org. + * + * 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, in version 3 of the + * License. + * + * 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, see <https://www.gnu.org/licenses>. + * + * SPDX-License-Identifier: GPL-3.0-only + */ + +/** @page pg_vbox_makefile_guidelines VBox Makefile Guidelines + * + * These guidelines apply to all the Makefile.kmk files in the tree. + * No exceptions. + * + * All these makefiles are ultimately the responsiblity of bird. Since there + * are currently more than three hundred files and the number is growing, they + * have to be very kept uniform or it will become very difficult to maintain + * them and impossible do bulk refactoring. Thus these guidelines have no bits + * that are optional unlike the coding guidelines, and should be thought of as + * rules rather than guidelines. + * + * Note! The guidelines do not apply to the non-kBuild makefiles found in the + * source tree, like the ones shipped in the SDK and the ones for the + * linux kernel modules. + * + * + * @section sec_vbox_makefile_guidelines_kbuild kBuild + * + * kBuild is way older than VirtualBox, at least as a concept, but the + * VirtualBox project was a push to get something done about it again. It's + * maintained by bird in his spare time because: "We don't make buildsystems, we + * make virtual machines". So, kBuild makes progress when there is spare time + * or when there is an urgent need for something. + * + * The kBuild docs are in the process of being written. The current items and + * their status per 2018-10-29: + * - kmk Quick Reference [completed]: + * http://svn.netlabs.org/kbuild/wiki/kmk%20Quick%20Reference + * - kBuild Quick Reference [just started]: + * http://svn.netlabs.org/kbuild/wiki/kBuild%20Quick%20Reference + * + * Local copies of the docs can be found in kBuild/docs, just keep in mind that + * they might be slightly behind the online version. + * + * + * @section sec_vbox_makefile_guidelines_example Example Makefiles + * + * Let me point to some good sample makefiles: + * - src/VBox/Additions/common/VBoxService/Makefile.kmk + * - src/VBox/Debugger/Makefile.kmk + * - src/VBox/Disassembler/Makefile.kmk + * + * And some bad ones: + * - src/lib/xpcom18a4/Makefile.kmk + * - src/recompiler/Makefile.kmk + * - src/VBox/Devices/Makefile.kmk + * - src/VBox/Main/Makefile.kmk + * - src/VBox/Runtime/Makefile.kmk + * + * + * @section sec_vbox_makefile_guidelines Guidelines + * + * First one really important fact: + * + * Everything is global because all makefiles + * are virtually one single makefile. + * + * The rules: + * + * - Using bits defined by a sub-makefile is fine, using anything defined + * by a parent, sibling, uncle, cousine, or remoter relatives is not + * Okay. It may break sub-tree building which is not acceptable. + * + * - Template names starts with VBox and are camel cased, no + * underscores or other separators. (Note this used to be all upper + * case, fixing this incomplete.) + * + * - Makefile variables shall be prefixed with VBOX or VB to avoid clashes + * with environment and kBuild variables. + * + * - Makefile variables are all upper cased and uses underscores to + * separate the words. + * + * - All variables are global. Make sure they are globally unique, but try + * not make them incredible long. + * + * - Makefile variables goes after the inclusion of the header and + * usually after including sub-makefiles. + * + * - Variables that are used by more than one makefile usually ends up + * in the monster file, Config.kmk. However, see if there are any + * sub-tree specific Config.kmk files that could do the job first. + * + * - Targets are lower or camel cased and as a rule the same as the + * resulting binary. + * + * - Install targets frequently have a -inst in their name, and a name that + * gives some idea what they install + * + * - Always use templates (mytarget_TEMPLATE = VBoxSomething). + * + * - Comment each target with a 3+ line block as seen in + * src/VBox/Debugger/Makefile.kmk. + * + * - No space between the comment block and the target definition. + * + * - Try fit all the custom recipes after the target they apply to. + * + * - Custom recipes that apply to more than one target should be placed at + * the bottom of the makefile, before the footer inclusion when possible. + * + * - Do NOT use custom recipes to install stuff, use install targets. + * Generate files to inst-target_0_OUTDIR. (Yes, there are a lot places + * where we don't do this yet.) + * + * - Always break SOURCES, LIBS, long target list and other lists the + * manner Debugger_SOURCES is broken into multiple lines in + * src/VBox/Debugger/Makefile.kmk. I.e. exactly one tab, the file name / + * list item, another space, the slash and then the newline. + * + * - Line continuation slashes shall never ever be aligned vertically (that + * always goes crooked sooner or later), but have exactly one space + * before them. + * + * - The last element of an broken list shall not have a slash-newline, + * otherwise we risk getting the next variable into the list. + * + * - When if'ed blocks come into play, we will only indent the conditional + * makefile directives (if, ifeq, ifneq, if1of, ifn1of, ifdef, ifndef, + * else, endif, ++), one space for each level. (Note! We used to indent + * non-directives, which made emacs upset as we'd have both tabs and + * spaces on as indentation on the same line. There are a lot of cases + * of this still around.) + * + * - \$(NO_SUCH_VARIABLE) should be when you need to put nothing somewhere, + * for instance to prevent inherting an attribute. + * + * - Always put the defines in the DEFS properties, never use the FLAGS + * properties for this. Doing so may screw up depenencies and object + * caches. + * + * - Mark each section and target of the file with a 3+ lines comment + * block. + * + * - Document variables that are not immediately obvious using double hash + * comments, doxygen style. + * + * - Each an every Makefile.kmk shall have a file header with Id, file + * description and copyright/license exactly like in the examples. (The + * SCM tool will complain if you don't.) + * + * - Multiple blank lines in a makefile is very seldom there without a + * reason and shall be preserved. + * + * - Inserting blank lines between target properties is all right if the + * target definition is long and/or crooked. + * + * - if1of and ifn1of shall always have a space after the comma, while ifeq + * and ifneq shall not. That way they are easier to tell apart. + * + * - Do a svn diff before committing makefile changes. + * + * + * @section sec_vbox_makefile_guidelines_reminders Helpful reminders + * + * - Do not be afraid to ask for help on IRC or in the defect you're + * working on. There are usually somebody around that know how to best do + * something. + * + * - Watch out for "Heads Up!" bugtracker messages concerning the build + * system. + * + * - To remove bits from a template you're using you have to create a new + * template that extends the existing one and creatively use + * \$(filter-out) or \$(patsubst). + * + * - You can build sub-trees. + * + * - You don't have to cd into sub-trees: kmk -C src/recompiler + * + * - You can build individual targets: kmk VBoxRT + * + * - Even install targets: kmk nobin + * + * - You can compile individual source files: kmk ConsoleImpl.o + * + * - You can tell kmk to continue on failure: kmk -k + * + * - You can tell kmk to run at low priority: kmk --nice + * + * - The --pretty-command-printing option is useful for seeing exactly + * what's passed to the tools. + * + * - You can invoke recipes in the root makefile more efficiently via the + * Maintenance.kmk file: kmk -f Maintenance.kmk incs + * + */ + diff --git a/doc/VBox-doc.c b/doc/VBox-doc.c new file mode 100644 index 00000000..c8114b1f --- /dev/null +++ b/doc/VBox-doc.c @@ -0,0 +1,219 @@ +/* $Id: VBox-doc.c $ */ +/** @file + * VirtualBox Top Level Documentation File. + */ + +/* + * Copyright (C) 2006-2023 Oracle and/or its affiliates. + * + * This file is part of VirtualBox base platform packages, as + * available from https://www.virtualbox.org. + * + * 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, in version 3 of the + * License. + * + * 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, see <https://www.gnu.org/licenses>. + * + * SPDX-License-Identifier: GPL-3.0-only + */ + + +/** @mainpage VirtualBox + * + * (add introduction here) + * + * @section pg_main_comp Components + * + * - VM / @ref pg_vmm "VMM" / GVM / @ref pg_gvmm "GVMM" - Virtual Machine + * Monitor. + * - @ref pg_cfgm + * - @ref pg_cpum + * - @ref pg_dbgf + * - @ref pg_dbgf_addr_space + * - @ref pg_dbgf_vmcore + * - @ref pg_dbgf_module + * - @ref pg_dbgc + * - VBoxDbg - Debugger GUI (Qt). + * - @ref grp_dis + * - @ref pg_em + * - @ref pg_gim + * - @ref pg_hm + * - @ref pg_iem + * - @ref pg_nem + * - @ref pg_gmm + * - @ref pg_mm + * - @ref pg_pgm + * - @ref pg_pgm_phys + * - @ref pg_pgm_pool + * - @ref pg_selm + * - @ref pg_iom + * - @ref pg_pdm + * - Devices / USB Devices, Drivers and their public interfaces. + * - Async I/O Completion API. + * - Async Task API. + * - Critical Section API. + * - Queue API. + * - Thread API. + * - @ref pg_pdm_block_cache + * - @ref pg_ssm + * - @ref pg_stam + * - @ref pg_tm + * - @ref pg_trpm + * - VMM docs: + * - @ref pg_vmm_guideline + * - @ref pg_raw + * - Pluggable Components (via PDM). + * - DevPCArch - PC Architecture Device (chipset, legacy ++). + * - DevPCBios - Basic Input Output System. + * - DevDMAC - DMA Controller. + * - DevPIC - Programmable Interrupt Controller. + * - DevPIT - Programmable Interval Timer (i8254). + * - DevRTC - Real Time Clock. + * - DevVGA - Video Graphic Array. + * - DevPCI - Peripheral Component Interface (Bus). + * - VBoxDev - Special PCI Device which serves as an interface between + * the VMM and the guest OS for the additions. + * - @ref pg_pdm_audio "Audio": + * - DevHda - Intel High Definition Audio Device Emulation. + * - DevIchAc97 - ICH AC'97 Device Emulation. + * - DevSB16 - SoundBlaster 16 Device Emulation. + * - DrvAudio - Intermediate driver. + * - DrvHostAudioAlsa - ALSA Host Audio Driver (Linux). + * - DrvHostAudioCoreAudio - Core Audio Host Audio Driver (macOS). + * - DrvHostAudioDebug - Debug Backend Driver. + * - DrvHostAudioDSound - DirectSound Host Audio Driver (Windows). + * - DrvHostAudioNull - NULL Backend Driver. + * - DrvHostAudioOss - Open Sound System Host Audio Driver (Linux, + * Solaris, ++). + * - DrvHostAudioPulseAudio - PulseAudio Host Audio Driver (Linux). + * - DrvHostAudioValidationKit - Validation Kit Test Driver. + * - DrvHostAudioWasApi - Windows Audio Session API Host Audio Driver. + * - Networking: + * - DevPCNet - AMD PCNet Device Emulation. + * - DevE1000 - Intel E1000 Device Emulation. + * - DevEEPROM - Intel E1000 EPROM Device Emulation. + * - SrvINetNetR0 - Internal Networking Ring-0 Service. + * - DevINIP - IP Stack Service for the internal networking. + * - DrvIntNet - Internal Networking Driver. + * - DrvNetSniffer - Wireshark Compatible Sniffer Driver (pass thru). + * - DrvNAT - Network Address Translation Driver. + * - DrvTAP - Host Interface Networking Driver. + * - Storage: + * - DevATA - ATA ((E)IDE) Device Emulation. + * - @ref pg_dev_ahci + * - DevFDC - Floppy Controller Device Emulation. + * - DrvBlock - Intermediate block driver. + * - DrvHostBase - Common code for the host drivers. + * - DrvHostDVD - Host DVD drive driver. + * - DrvHostFloppy - Host floppy drive driver. + * - DrvHostRawDisk - Host raw disk drive driver. + * - DrvMediaISO - ISO media driver. + * - DrvRawImage - Raw image driver (floppy images etc). + * - DrvVD - Intermediate Virtual Drive (Media) driver. + * - DrvVDI - VirtualBox Drive Image Container Driver. + * - DrvVmdk - VMDK Drive Image Container Driver. + * - USB: + * - @ref pg_dev_ohci + * - @ref pg_dev_ehci + * - @ref pg_dev_vusb + * - @ref pg_dev_vusb_old + * - Host Drivers. + * - SUPDRV - The Support driver (aka VBoxDrv). + * - @ref pg_sup + * - @ref pg_netflt + * - @ref pg_netadp + * - VBoxUSB - The USB support driver. + * - @ref pg_netflt + * - @ref pg_rawpci + * - Host Services. + * - @ref pg_hostclip + * - Shared Folders. + * - @ref pg_svc_guest_properties + * - @ref pg_svc_guest_control + * - Guest Additions. + * - VBoxGuest. + * - @ref pg_guest_lib + * - @ref pg_vgsvc + * - @ref pg_vgsvc_timesync + * - @ref pg_vgsvc_vminfo + * - @ref pg_vgsvc_vmstats + * - @ref pg_vgsvc_gstctrl + * - @ref pg_vgsvc_pagesharing + * - @ref pg_vgsvc_memballoon + * - @ref pg_vgsvc_cpuhotplug + * - @ref pg_vgsvc_automount + * - @ref pg_vgsvc_clipboard + * - VBoxControl. + * - Linux, Solaris and FreeBSD specific guest services and drivers. + * - @ref pg_vboxdrmcliet (Linux only). + * - VBoxClient. + * - VBoxVideo. + * - Windows Guests. + * - VBoxTray. + * - crOpenGL. + * - pam. + * - ... + * - Network Services: + * - @ref pg_net_dhcp + * - NAT + * - @ref pg_main + * - @ref pg_main_events + * - @ref pg_vrdb_usb + * - Frontends: + * - VirtualBox - The default Qt-based GUI. + * - VBoxHeadless - The headless frontend. + * - VBoxManage - The CLI. + * - VBoxShell - An interactive shell written in python. + * - VBoxSDL - A very simple GUI. + * - VBoxBFE - A bare metal edition which does not use COM/XPCOM (barely + * maintained atm). + * - IPRT - Runtime Library for hiding host OS differences. + * - Validation Kit: + * - @ref pg_validationkit_guideline + * - @ref pg_bs3kit + * - @ref pg_vbox_guideline + * + * @todo Make links to the components. + * + * + * + * @section Execution Contexts + * + * VirtualBox defines a number of different execution context, this can be + * confusing at first. So, to start with take a look at this diagram: + * + * @image html VMMContexts.png + * + * Context definitions: + * - Host context (HC) - This is the context where the host OS runs and + * runs VirtualBox within it. The absense of IN_RC and IN_GUEST + * indicates that we're in HC. IN_RING0 indicates ring-0 (kernel) and + * IN_RING3 indicates ring-3. + * - Raw-mode Context (RC) - This is the special VMM context where we + * execute the guest code directly on the CPU. Kernel code is patched + * and execute in ring-1 instead of ring-0 (ring compression). Ring-3 + * code execute unmodified. Only VMMs use ring-1, so we don't need to + * worry about that (it's guarded against in the scheduler (EM)). We can + * in theory run ring-2 there, but since practially only only OS/2 uses + * ring-2, it is of little importance. The macro IN_RC indicates that + * we're compiling something for RC. + * Note! This used to be called GC (see below) earlier, so a bunch of RC + * things are using GC markers. + * - Guest Context (GC) - This is where the guest code is executed. When + * compiling, IN_GUEST indicates that it's for GC. IN_RING0 and + * IN_RING3 are also set when applicable, these are accompanied by + * IN_GUEST_R0 and IN_GUEST_R3 respecitively. + * - Intermediate context - This is a special memory context used within + * the world switchers (HC -> RC and back), it features some identity + * mapped code pages so we can switch to real mode if necessary. + * + */ + diff --git a/doc/VMM/PDMStorageScsi.odg b/doc/VMM/PDMStorageScsi.odg Binary files differnew file mode 100644 index 00000000..af912b80 --- /dev/null +++ b/doc/VMM/PDMStorageScsi.odg diff --git a/doc/VMM/PDMStorageScsi.png b/doc/VMM/PDMStorageScsi.png Binary files differnew file mode 100644 index 00000000..519c0488 --- /dev/null +++ b/doc/VMM/PDMStorageScsi.png diff --git a/doc/VMM/VMMContexts.odg b/doc/VMM/VMMContexts.odg Binary files differnew file mode 100644 index 00000000..5cd9f6b3 --- /dev/null +++ b/doc/VMM/VMMContexts.odg diff --git a/doc/VMM/VMMContexts.png b/doc/VMM/VMMContexts.png Binary files differnew file mode 100644 index 00000000..21f371be --- /dev/null +++ b/doc/VMM/VMMContexts.png diff --git a/doc/kBuild-tricks.txt b/doc/kBuild-tricks.txt new file mode 100644 index 00000000..f5a1bbda --- /dev/null +++ b/doc/kBuild-tricks.txt @@ -0,0 +1,62 @@ + +kBuild / VBox Build Tricks +========================== + + +Introduction +------------ + +This document is written in reStructuredText (rst) which just happens to +be used by Python, the primary language for this revamp. For more information +on reStructuredText: http://docutils.sourceforge.net/rst.html + + +Changing the output directory +----------------------------- + +When switch between different VBox build settings it can be nice to have +different output directories to avoid having to rebuild the whole source tree +everything. One typical example is hardening, another is guest additions using +crossbuild gcc w/ SDK. The latter is is simpler so that's the first example: + +.. code:: makefile + + ifdef VBOX_WITH_COMPATIBLE_LINUX_GUEST_PACKAGE + PATH_OUT_BASE = $(PATH_ROOT)/add-out + endif + +The following example is the typical developer setup, i.e. disable hardening by +default but respect command line overrides (kmk VBOX_WITH_HARDENING=1): + +.. code:: make + + VBOX_WITH_HARDENING := + ifeq ($(VBOX_WITH_HARDENING),) + VBOX_WITHOUT_HARDENING=1 + else + PATH_OUT_BASE = $(PATH_ROOT)/hard-out + endif + + +Share tools download directory between trunk and branches +--------------------------------------------------------- + +To avoid filling up your disk with unnecessary tool zip and tar.gz files, set +the FETCHDIR variable in LocalConfig.kmk to point to a common directory for all +VBox checkouts. + +.. code:: make + + FETCHDIR = $(HOME)/Downloads/FetchDir + + +----- + +.. [1] no such footnote + + +----- + +:Status: $Id: kBuild-tricks.txt $ +:Copyright: Copyright (C) 2006-2022 Oracle Corporation. + diff --git a/doc/manual/.scm-settings b/doc/manual/.scm-settings new file mode 100644 index 00000000..fc945a47 --- /dev/null +++ b/doc/manual/.scm-settings @@ -0,0 +1,33 @@ +# $Id: .scm-settings $ +## @file +# Source code massager settings for the manual. +# + +# +# Copyright (C) 2010-2023 Oracle and/or its affiliates. +# +# This file is part of VirtualBox base platform packages, as +# available from https://www.virtualbox.org. +# +# 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, in version 3 of the +# License. +# +# 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, see <https://www.gnu.org/licenses>. +# +# SPDX-License-Identifier: GPL-3.0-only +# + + +/string.xsl: --external-copyright --no-convert-tabs +/titlepage-htmlhelp.xml: --external-copyright --no-convert-tabs + +--filter-out-dirs /texfiles/. + diff --git a/doc/manual/Config.kmk b/doc/manual/Config.kmk new file mode 100644 index 00000000..8777cb6c --- /dev/null +++ b/doc/manual/Config.kmk @@ -0,0 +1,423 @@ +# $Id: Config.kmk $ +## @file +# kBuild Configuration file for the manual. +# + +# +# Copyright (C) 2010-2023 Oracle and/or its affiliates. +# +# This file is part of VirtualBox base platform packages, as +# available from https://www.virtualbox.org. +# +# 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, in version 3 of the +# License. +# +# 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, see <https://www.gnu.org/licenses>. +# +# SPDX-License-Identifier: GPL-3.0-only +# + +ifndef VBOX_DOC_MANUAL_CONFIG_KMK_INCLUDED + VBOX_DOC_MANUAL_CONFIG_KMK_INCLUDED = 1 + + # Include the top-level configure file. + ifndef VBOX_ROOT_CONFIG_KMK_INCLUDED + include $(PATH_ROOT)/Config.kmk + endif + + + # + # Globals. + # + + # Source location. + VBOX_PATH_MANUAL_SRC := $(PATH_ROOT)/doc/manual + # Output location. + VBOX_PATH_MANUAL_OUTBASE := $(PATH_OBJ)/manual + + ## List of refentry files (manpages). + VBOX_MANUAL_XML_REFENTRY_FILES := \ + man_VBoxManage-common.xml \ + man_VBoxManage-list.xml \ + man_VBoxManage-showvminfo.xml \ + man_VBoxManage-registervm.xml \ + man_VBoxManage-unregistervm.xml \ + man_VBoxManage-createvm.xml \ + man_VBoxManage-modifyvm.xml \ + man_VBoxManage-snapshot.xml \ + man_VBoxManage-clonevm.xml \ + man_VBoxManage-movevm.xml \ + man_VBoxManage-encryptvm.xml \ + man_VBoxManage-startvm.xml \ + man_VBoxManage-controlvm.xml \ + man_VBoxManage-import.xml \ + man_VBoxManage-export.xml \ + man_VBoxManage-mediumio.xml \ + man_VBoxManage-sharedfolder.xml \ + man_VBoxManage-dhcpserver.xml \ + man_VBoxManage-debugvm.xml \ + man_VBoxManage-extpack.xml \ + man_VBoxManage-unattended.xml \ + man_VBoxManage-cloud.xml \ + man_VBoxManage-cloudprofile.xml \ + man_VBoxManage-signova.xml \ + man_VBoxManage-modifynvram.xml \ + man_VBoxManage-hostonlynet.xml \ + man_VBoxManage-updatecheck.xml \ + man_VBoxManage-discardstate.xml \ + man_VBoxManage-adoptstate.xml \ + man_VBoxManage-closemedium.xml \ + man_VBoxManage-storageattach.xml \ + man_VBoxManage-storagectl.xml \ + man_VBoxManage-bandwidthctl.xml \ + man_VBoxManage-showmediuminfo.xml \ + man_VBoxManage-createmedium.xml \ + man_VBoxManage-modifymedium.xml \ + man_VBoxManage-clonemedium.xml \ + man_VBoxManage-mediumproperty.xml \ + man_VBoxManage-encryptmedium.xml \ + man_VBoxManage-checkmediumpwd.xml \ + man_VBoxManage-convertfromraw.xml \ + man_VBoxManage-setextradata.xml \ + man_VBoxManage-getextradata.xml \ + man_VBoxManage-setproperty.xml \ + man_VBoxManage-usbfilter.xml \ + man_VBoxManage-guestproperty.xml \ + man_VBoxManage-guestcontrol.xml \ + man_VBoxManage-metrics.xml \ + man_VBoxManage-natnetwork.xml \ + man_VBoxManage-hostonlyif.xml \ + man_VBoxManage-usbdevsource.xml + + ## List of user manual XML files. + VBOX_MANUAL_XML_FILES = \ + UserManual.xml \ + user_Preface.xml \ + user_Introduction.xml \ + user_Installation.xml \ + user_BasicConcepts.xml \ + user_GuestAdditions.xml \ + user_Storage.xml \ + user_Networking.xml \ + user_Frontends.xml \ + user_VBoxManage.xml \ + user_AdvancedTopics.xml \ + user_Technical.xml \ + user_VirtualBoxAPI.xml \ + user_Troubleshooting.xml \ + user_Security.xml \ + user_KnownIssues.xml \ + user_ChangeLog.xml \ + user_ThirdParty.xml \ + user_PrivacyPolicy.xml \ + user_Glossary.xml \ + oracle-accessibility-ohc-en.xml \ + oracle-diversity.xml \ + oracle-support-en.xml + + ## List of user manual XML files common for all languages. + VBOX_MANUAL_XML_FILES_COMMON = \ + $(VBOX_PATH_MANUAL_SRC)/user_ChangeLogImpl.xml + + + # Tool locations. + ifndef VBOX_OSE + # use docbook from our tools directory + VBOX_PATH_DOCBOOK ?= $(KBUILD_DEVTOOLS)/common/DocBook/v1.69.1 + VBOX_PATH_DOCBOOK_DTD ?= $(KBUILD_DEVTOOLS)/common/docbook-xml/v4.5 + else + # use docbook of the build host + VBOX_PATH_DOCBOOK ?= /usr/share/xml/docbook/stylesheet/docbook-xsl + VBOX_PATH_DOCBOOK_DTD ?= /usr/share/xml/docbook/schema/dtd/4.5 + endif + VBOX_XML_CATALOG ?= $(VBOX_PATH_MANUAL_OUTBASE)/vbox-doc.cat + VBOX_XML_CATALOG_DOCBOOK ?= $(VBOX_PATH_MANUAL_OUTBASE)/docbook.cat + VBOX_XML_CATALOG_MANUAL ?= $(VBOX_PATH_MANUAL_OUTBASE)/manual.cat + VBOX_XML_ENTITIES ?= $(VBOX_PATH_MANUAL_OUTBASE)/all-entities.ent + + # xsltproc with the catalog trick if applicable (set XML_DEBUG_CATALOG to + # non-zero value to debug file/uri resolution through the catalogs, using + # one of them is enough, they show the same information). + ifdef VBOX_XML_CATALOG + VBOX_XSLTPROC_WITH_CAT = $(REDIRECT) -E "XML_CATALOG_FILES=$(if $(2),$(2),$(VBOX_XML_CATALOG))" -E "XML_DEBUG_CATALOG=" $1 -- \ + $(VBOX_XSLTPROC) --nonet --xinclude $(VBOX_XSLTPROC_OPTS) --path "$(VBOX_PATH_MANUAL_OUTBASE)" + VBOX_XMLLINT_WITH_CAT = $(REDIRECT) -E "XML_CATALOG_FILES=$(VBOX_XML_CATALOG)" -E "XML_DEBUG_CATALOG=" -- \ + $(VBOX_XMLLINT) --nonet --xinclude --noout $(VBOX_XMLLINT_OPTS) --path "$(VBOX_PATH_MANUAL_OUTBASE)" + else + VBOX_XSLTPROC_WITH_CAT = $(if $(1), $(REDIRECT) $1 --,) $(VBOX_XSLTPROC) --nonet --xinclude $(VBOX_XSLTPROC_OPTS) \ + --path "$(VBOX_PATH_MANUAL_OUTBASE)" + VBOX_XMLLINT_WITH_CAT = $(VBOX_XMLLINT) --nonet --xinclude --noout $(VBOX_XMLLINT_OPTS) --path "$(VBOX_PATH_MANUAL_OUTBASE)" + endif + + + # File name of the generated stylesheet for transforming xref elements into + # name user manual sections. + VBOX_XML_XREF_TO_TEXT = xref-to-text.xsl + + ## + # Emits rules for preprocessing refentry sources (applying remarks element), + # and for producing the actual man pages. + # + # $(evalcall2 def_vbox_refentry_preprocess_for_manpage) + # @param 1 The output directory. + # @param 2 The XML file name (no path). + # @param 3 The XML file with full path. + # @param 4 Non-empty if xrefs to replace. + # @param 5 Language code (optional if $4 is empty). + define def_vbox_refentry_preprocess_for_manpage + $(1)/$(2): \ + $(3) \ + $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl \ + $(if $(4), $$(VBOX_PATH_MANUAL_OUTBASE)/$(5)/$$(VBOX_XML_XREF_TO_TEXT),) \ + $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \ + $$(VBOX_VERSION_STAMP) | $$$$(dir $$$$@) + $$(call MSG_TOOL,xsltproc $$(notdir $$(firstword $$(filter %.xsl,$$^))),,$$(firstword $$(filter %.xml,$$^)),$$@) + $$(QUIET)$$(RM) -f "$$@" + $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$@ \ + "$$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl" $$< + ifneq ($(4),) + $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$@.tmp \ + $$(VBOX_PATH_MANUAL_OUTBASE)/$(5)/$$(VBOX_XML_XREF_TO_TEXT) $$@ + $$(QUIET)$$(MV) -f -- "$$@.tmp" "$$@" + endif + if defined(VBOX_HAVE_XMLLINT) && "$(USER)" == "bird" # Effing stuff happends on build servers, probably kmk related... + $$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $$(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $$@ + endif + endef + + ## + # Generate a single header file containing everything (no C file). + # + # @param 1 Destination file. + # @param 2 Full source file path. + # @param 3 Help infix. + define def_vbox_single_refentry_to_h + $(1).ts +| $(1): \ + $$(VBOX_DOCBOOK_REFENTRY_TO_C_HELP) \ + $$(VBOX_DOCBOOK_REFENTRY_TO_H_HELP) \ + $(2) \ + $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) $(MAKEFILE) | $$$$(dir $$$$@) + $$(call MSG_TOOL,xsltproc $$(notdir $$(firstword $$(filter %.xsl,$$^))),,$$(filter %.xml,$$^),$$(patsubst %.ts,%,$$@)) + $$(QUIET)$$(APPEND) -tn "$$@" \ + '/* Autogenerated by $$(notdir $$(filter %.xsl,$$^)), do not edit! */' \ + '' \ + '#include <iprt/message.h>' \ + '#include <iprt/assertcompile.h>' \ + '' \ + 'typedef enum HELP_CMD_$(3)' \ + '{' \ + ' HELP_CMD_INVALID = 0,' + $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT, -a+to "$$@") \ + --stringparam 'g_sMode' 'cmd' $$(VBOX_DOCBOOK_REFENTRY_TO_H_HELP) $(2) + $$(QUIET)$$(APPEND) -n "$$@" \ + ' HELP_CMD_END' \ + '} HELP_CMD_VBOXMANAGE;' \ + '' + $$(NLTAB)$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT, -a+to "$$@") \ + --stringparam 'g_sMode' 'subcmd' $$(VBOX_DOCBOOK_REFENTRY_TO_H_HELP) $(2) + $$(QUIET)$$(APPEND) -n "$$@" \ + '' + $$(NLTAB)$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT, -a+to "$$@") $$(VBOX_DOCBOOK_REFENTRY_TO_C_HELP) $(2) + $$(QUIET)$$(APPEND) -n "$$@" \ + '' \ + '/* end of file */' + $$(QUIET)$$(CP) --changed -- "$$@" "$$(patsubst %.ts,%,$$@)" + endef + + + # + # Make sure we've got a rule to make the output directory. + # + BLDDIRS += $(VBOX_PATH_MANUAL_OUTBASE) + + + ifdef VBOX_XML_CATALOG + # Trickery for making sure that the file:/// URLs end up with exactly 3 + # slashes, both on Unixy OSes (where the absolute path contributes one more, + # and some very picky xsltproc variants are floating around which do not work + # quite correctly with file:////, doing incorrect filename transformations) + # and on Windows (where the absolute path starts with a drive letter). + VBOX_FILE_URL_MAYBE_SLASH = $(if $(eq $(KBUILD_HOST),win),/,) + # + # To avoid network I/O for fetching DTDs, we generate catalogs mapping the public + # entity IDs to local files. (Obviously, only done when we have local files.) + # + # Create a catalog file for xsltproc that points to docbook catalog. + $(VBOX_XML_CATALOG): $(VBOX_PATH_MANUAL_SRC)/Config.kmk | $$(dir $$@) + $(call MSG_L1,Creating catalog $@) + $(QUIET)$(APPEND) -tn "$@" \ + '<?xml version="1.0"?>' \ + '<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">' \ + '<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">' \ + ' <delegatePublic publicIdStartString="-//OASIS/ENTITIES DocBook XML" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_DOCBOOK)"/>' \ + ' <delegatePublic publicIdStartString="-//OASIS/DTD DocBook XML" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_DOCBOOK)"/>' \ + ' <delegateSystem systemIdStartString="http://www.oasis-open.org/docbook/" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_DOCBOOK)"/>' \ + ' <delegateSystem systemIdStartString="http://docbook.org/" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_DOCBOOK)"/>' \ + ' <delegateURI uriStartString="http://www.oasis-open.org/docbook/" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_DOCBOOK)"/>' \ + ' <delegateURI uriStartString="http://docbook.org/" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_DOCBOOK)"/>' \ + ' <delegateSystem systemIdStartString="$(VBOX_PATH_MANUAL_SRC)" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_MANUAL)"/>' \ + ' <delegateSystem systemIdStartString="$(VBOX_PATH_MANUAL_OUTBASE)" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_MANUAL)"/>' \ + ' <delegateURI uriStartString="$(VBOX_PATH_MANUAL_SRC)" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_MANUAL)"/>' \ + ' <delegateURI uriStartString="$(VBOX_PATH_MANUAL_OUTBASE)" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_MANUAL)"/>' \ + ' <delegateURI uriStartString="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_MANUAL_SRC)" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_MANUAL)"/>' \ + ' <delegateURI uriStartString="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_MANUAL_OUTBASE)" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_MANUAL)"/>' \ + '</catalog>' + + # Create a docbook catalog file for xsltproc that points to the local docbook files. + $(VBOX_XML_CATALOG_DOCBOOK): $(VBOX_PATH_MANUAL_SRC)/Config.kmk | $$(dir $$@) + $(call MSG_L1,Creating catalog $@) + $(QUIET)$(APPEND) -tn "$@" \ + '<?xml version="1.0"?>' \ + '<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">' \ + '<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">' \ + ' <public publicId="-//OASIS//ELEMENTS DocBook XML Information Pool V4.5//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/dbpoolx.mod"/>' \ + ' <public publicId="-//OASIS//DTD DocBook XML V4.5//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd"/>' \ + ' <public publicId="-//OASIS//ENTITIES DocBook XML Character Entities V4.5//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/dbcentx.mod"/>' \ + ' <public publicId="-//OASIS//ENTITIES DocBook XML Notations V4.5//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/dbnotnx.mod"/>' \ + ' <public publicId="-//OASIS//ENTITIES DocBook XML Additional General Entities V4.5//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/dbgenent.mod"/>' \ + ' <public publicId="-//OASIS//ELEMENTS DocBook XML Document Hierarchy V4.5//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/dbhierx.mod"/>' \ + ' <public publicId="-//OASIS//DTD XML Exchange Table Model 19990315//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/soextblx.dtd"/>' \ + ' <public publicId="-//OASIS//DTD DocBook XML CALS Table Model V4.5//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/calstblx.dtd"/>' \ + ' <rewriteSystem systemIdStartString="http://www.oasis-open.org/docbook/xml/4.5" rewritePrefix="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)"/>' \ + ' <rewriteSystem systemIdStartString="http://docbook.org/xml/4.5" rewritePrefix="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)"/>' \ + ' <rewriteURI uriStartString="http://www.oasis-open.org/docbook/xml/4.5" rewritePrefix="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)"/>' \ + ' <rewriteURI uriStartString="http://docbook.org/xml/4.5" rewritePrefix="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)"/>' \ + ' <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Arrow Relations//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-amsa.ent"/>' \ + ' <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Binary Operators//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-amsb.ent"/>' \ + ' <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Delimiters//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-amsc.ent"/>' \ + ' <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Negated Relations//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-amsn.ent"/>' \ + ' <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Ordinary//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-amso.ent"/>' \ + ' <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Relations//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-amsr.ent"/>' \ + ' <public publicId="ISO 8879:1986//ENTITIES Box and Line Drawing//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-box.ent"/>' \ + ' <public publicId="ISO 8879:1986//ENTITIES Russian Cyrillic//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-cyr1.ent"/>' \ + ' <public publicId="ISO 8879:1986//ENTITIES Non-Russian Cyrillic//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-cyr2.ent"/>' \ + ' <public publicId="ISO 8879:1986//ENTITIES Diacritical Marks//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-dia.ent"/>' \ + ' <public publicId="ISO 8879:1986//ENTITIES Greek Letters//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-grk1.ent"/>' \ + ' <public publicId="ISO 8879:1986//ENTITIES Monotoniko Greek//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-grk2.ent"/>' \ + ' <public publicId="ISO 8879:1986//ENTITIES Greek Symbols//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-grk3.ent"/>' \ + ' <public publicId="ISO 8879:1986//ENTITIES Alternative Greek Symbols//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-grk4.ent"/>' \ + ' <public publicId="ISO 8879:1986//ENTITIES Added Latin 1//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-lat1.ent"/>' \ + ' <public publicId="ISO 8879:1986//ENTITIES Added Latin 2//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-lat2.ent"/>' \ + ' <public publicId="ISO 8879:1986//ENTITIES Numeric and Special Graphic//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-num.ent"/>' \ + ' <public publicId="ISO 8879:1986//ENTITIES Publishing//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-pub.ent"/>' \ + ' <public publicId="ISO 8879:1986//ENTITIES General Technical//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-tech.ent"/>' \ + '</catalog>' + + # Create a docbook catalog file for xsltproc that points to the local manual files in non-default locations + $(VBOX_XML_CATALOG_MANUAL): $(VBOX_PATH_MANUAL_SRC)/Config.kmk | $$(dir $$@) + $(call MSG_L1,Creating catalog $@) + $(QUIET)$(APPEND) -tn "$@" \ + '<?xml version="1.0"?>' \ + '<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">' \ + '<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">' \ + ' <system systemId="$(VBOX_PATH_MANUAL_SRC)/common/oracle-accessibility-ohc-en.xml" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_MANUAL_SRC)/en_US/oracle-accessibility-ohc-en.xml"/>' \ + ' <system systemId="$(VBOX_PATH_MANUAL_SRC)/common/oracle-legal-notices/oracle-diversity.xml" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_MANUAL_SRC)/en_US/oracle-diversity.xml"/>' \ + ' <system systemId="$(VBOX_PATH_MANUAL_SRC)/common/oracle-legal-notices/oracle-support-en.xml" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_MANUAL_SRC)/en_US/oracle-support-en.xml"/>' \ + ' <system systemId="$(VBOX_PATH_MANUAL_SRC)/en_US/user_ChangeLogImpl.xml" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_MANUAL_SRC)/user_ChangeLogImpl.xml"/>' \ + ' <system systemId="$(VBOX_PATH_MANUAL_SRC)/titlepage-htmlhelp.xsl" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_MANUAL_OUTBASE)/titlepage-htmlhelp.xsl"/>' \ + $(foreach x,user_VBoxManage_CommandsOverview.xml user_isomakercmd-man.xml $(addprefix user_,$(VBOX_MANUAL_XML_REFENTRY_FILES) man_VBoxHeadless.xml man_vboximg-mount.xml)\ + ,' <system systemId="$(VBOX_PATH_MANUAL_SRC)/en_US/$(x)" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_MANUAL_OUTBASE)/en_US/$(x)"/>' \$(NLTAB)$(TAB)) \ + ' <system systemId="$(VBOX_PATH_MANUAL_SRC)/en_US/SDKRef_apiref.xml" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef_apiref.xml"/>' \ + ' <system systemId="$(VBOX_PATH_MANUAL_SRC)/en_US/all-entities.ent" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_MANUAL_OUTBASE)/all-entities.ent"/>' \ + ' <system systemId="$(VBOX_PATH_MANUAL_SRC)/html/docbook.xsl" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK)/html/docbook.xsl"/>' \ + ' <system systemId="$(VBOX_PATH_MANUAL_SRC)/html/chunk.xsl" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK)/html/chunk.xsl"/>' \ + ' <system systemId="$(VBOX_PATH_MANUAL_SRC)/htmlhelp/htmlhelp.xsl" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK)/htmlhelp/htmlhelp.xsl"/>' \ + ' <system systemId="$(VBOX_PATH_MANUAL_SRC)/manpages/docbook.xsl" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK)/manpages/docbook.xsl"/>' \ + '</catalog>' + + endif # VBOX_XML_CATALOG + + + ifdef VBOX_XML_ENTITIES + + $(VBOX_XML_ENTITIES): $(VBOX_PATH_MANUAL_SRC)/Config.kmk $(VBOX_VERSION_STAMP) | $$(dir $$@) + $(call MSG_L1,Creating entities $@) + $(QUIET)$(APPEND) -tn "$@" \ + '<!-- Entities for product names -->' \ + '<!ENTITY product-version "$(VBOX_VERSION_STRING)">' \ + '<!ENTITY product-name "Oracle VM VirtualBox">' \ + '<!ENTITY vbox-mgr "VirtualBox Manager">' \ + '<!ENTITY oci "Oracle Cloud Infrastructure">' \ + '' \ + '<!-- VBox placeholder entities -->' \ + '<!ENTITY VBOX_VERSION_MAJOR "$(VBOX_VERSION_MAJOR)" >' \ + '<!ENTITY VBOX_VERSION_MINOR "$(VBOX_VERSION_MINOR)" >' \ + '<!ENTITY VBOX_VERSION_BUILD "$(VBOX_VERSION_BUILD)" >' \ + '<!ENTITY VBOX_VERSION_STRING "$(VBOX_VERSION_STRING)" >' \ + '<!ENTITY VBOX_VENDOR "$(VBOX_VENDOR)" >' \ + '<!ENTITY VBOX_C_YEAR "$(VBOX_C_YEAR)" >' \ + '<!ENTITY VBOX_PRODUCT '\''<trademark class="registered">Oracle</trademark> VM <trademark class="registered">VirtualBox</trademark>'\'' >' \ + '' \ + '<!-- Entities for Oracle Help Center -->' \ + '<!ENTITY ohc-base-url "https://docs.oracle.com/en">' \ + '<!ENTITY ohc-doc-page "&ohc-base-url;/virtualization/virtualbox/index.html">' + + endif # VBOX_XML_ENTITIES + + + ## Emit rules to produce stylesheet for translating cross references (xref) + # to user manual chapters and sections in the man pages and --help output. + # + # Note! This requires processing UserManual.xml as a single document in order + # to get the correct chapter and section numbering, so we use a catalog + # file to replace the generated XML documents it includes with a dummy + # one. This reduces the dependencies and recipies we require to build + # VBoxManage and the RTIsoMaker (w/ derivatives). + # $(evalcall2 def_vbox_xref_to_text) + # @param 1 Language code. + define def_vbox_xref_to_text + $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$$(VBOX_XML_XREF_TO_TEXT) \ + + $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$$(VBOX_XML_XREF_TO_TEXT).cat: \ + $$(VBOX_PATH_MANUAL_SRC)/$(1)/docbook-refentry-link-replacement-xsl-gen.xsl \ + $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-link-replacement-xsl-gen.xsl \ + $$(addprefix $$(VBOX_PATH_MANUAL_SRC)/en_US/,$$(VBOX_MANUAL_XML_FILES)) \ + $$(VBOX_MANUAL_XML_FILES_COMMON) \ + $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) $$(VBOX_XML_ENTITIES) \ + | $$$$(dir $$$$@) + $$(call MSG_L1,Creating stylesheet $$@) + $$(QUIET)$$(APPEND) -nt "$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$$(VBOX_XML_XREF_TO_TEXT).cat" \ + '<?xml version="1.0"?>' \ + '<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">' \ + '<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">' \ + $$(foreach x, user_isomakercmd-man.xml \ + $$(addprefix user_,$$(VBOX_MANUAL_XML_REFENTRY_FILES) man_VBoxHeadless.xml man_vboximg-mount.xml) \ + $$(addprefix overview_,$$(VBOX_MANUAL_XML_REFENTRY_FILES)) \ + ,' <system systemId="$$(VBOX_PATH_MANUAL_SRC)/en_US/$$(x)" uri="file://$$(VBOX_FILE_URL_MAYBE_SLASH)$$(VBOX_PATH_MANUAL_SRC)/dummy-sect1.xml"/>' \$$(NLTAB)$$(TAB)) \ + ' <nextCatalog catalog="file://$$(VBOX_FILE_URL_MAYBE_SLASH)$$(VBOX_XML_CATALOG)"/>' \ + '</catalog>' + $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT,,$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$$(VBOX_XML_XREF_TO_TEXT).cat) \ + --stringparam 'g_sMode' 'first' --output "$$@" "$$<" $$(filter %UserManual.xml,$$^) + # Using en-US version as section and chapter names until user manual is translated as well + $$(foreach x, $$(VBOX_MANUAL_XML_REFENTRY_FILES)\ + ,$$(NLTAB)$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT, -ato "$$@") --stringparam 'g_sMode' 'append' \ + "$$<" "$$(VBOX_PATH_MANUAL_SRC)/en_US/$$(x)") + $$(QUIET)$$(APPEND) -n "$$@" '' '</xsl:stylesheet>' + + BLDDIRS += $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/ + endef + # generate rules for $(VBOX_XML_XREF_TO_TEXT) + $(evalcall2 def_vbox_xref_to_text,en_US) + + # + # Generate rules for editing the refentry to C/H style sheets. + # + VBOX_DOCBOOK_REFENTRY_TO_C_HELP = $(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-C-help.xsl + + VBOX_DOCBOOK_REFENTRY_TO_H_HELP = $(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-H-help.xsl + + # + # Manual dependency. + # + $(VBOX_PATH_MANUAL_OUTBASE)/docbook-refentry-to-C-help.xsl: $(VBOX_PATH_MANUAL_SRC)/common-formatcfg.xsl + + +endif # !defined(VBOX_DOC_MANUAL_CONFIG_KMK_INCLUDED) + diff --git a/doc/manual/Makefile.kmk b/doc/manual/Makefile.kmk new file mode 100644 index 00000000..d14dc963 --- /dev/null +++ b/doc/manual/Makefile.kmk @@ -0,0 +1,1004 @@ +# $Id: Makefile.kmk $ +## @file +# Sub-Makefile for the VirtualBox User Manual, SDK reference and other manuals. +# + +# +# Copyright (C) 2006-2023 Oracle and/or its affiliates. +# +# This file is part of VirtualBox base platform packages, as +# available from https://www.virtualbox.org. +# +# 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, in version 3 of the +# License. +# +# 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, see <https://www.gnu.org/licenses>. +# +# SPDX-License-Identifier: GPL-3.0-only +# + +# +# This slightly messy makefile transforms the DocBook XML source for the +# user manual into presentation output. We support two targets: +# +# -- UserManual.pdf, generated by LaTex +# +# -- VirtualBox.chm +# +# Both files end up in PATH_STAGE_BIN. +# +# Both targets indirectly depend on the XML files in this directory; +# "indirectly" because we first copy them to PATH_TARGET and hack them +# up a bit for variable substitution and such (see below). +# The toolchains are roughly like this: +# +# -- PDF file via Apache FOP: pre-process the XML files in PATH_TARGET, +# then create a .FO file (another XML format for "formatted objects") +# via xsltproc, then feed the .FO file to Apache FOP to create the PDF. +# +# -- PDF file via LaTeX: pre-process the XML files in PATH_TARGET, then +# run our custom "dblatex" perl script on UserManual.xml, which parses +# the XML (using the Perl SAX parsers) and dumps a matching LaTeX file +# to UserManual.tex. This is then regularly processed by pdflatex to +# generate PDF. +# +# -- CHM file: again, pre-process the XML files in PATH_TARGET, then use +# xsltproc to create a .HHP file for the Microsoft Help Compiler, then +# feed that file to it. +# + +SUB_DEPTH = ../.. +include $(KBUILD_PATH)/subheader.kmk + +ifndef VBOX_DOC_MANUAL_CONFIG_KMK_INCLUDED + include $(PATH_SUB_CURRENT)/Config.kmk +endif + + +# +# Globals +# + +# Error out if someone tries to override old globals. +ifdef HTMLHELPOPTS + $(error HTMLHELPOPTS was renamed to VBOX_HTMLHELP_OPTS!) +endif +ifdef DOCBOOKPATH + $(error DOCBOOKPATH was renamed to VBOX_PATH_DOCBOOK!) +endif +ifdef DOCBOOKPATH + $(error DOCBOOKPATH was renamed to VBOX_PATH_DOCBOOK!) +endif +ifdef XML_CATALOG + $(error XML_CATALOG was renamed to VBOX_XML_CATALOG!) +endif +ifdef XML_CATALOG_DOCBOOK + $(error XML_CATALOG_DOCBOOK was renamed to VBOX_XML_CATALOG_DOCBOOK!) +endif +ifdef PDFLATEX_INTERACTION + $(error PDFLATEX_INTERACTION was renamed to VBOX_PDFLATEX_INTERACTION!) +endif +ifdef PDFLATEX + $(error PDFLATEX was renamed to VBOX_PDFLATEX_CMD!) +endif +ifdef HHC + $(error HHC was renamed to VBOX_HHC!) +endif + +VBOX_QHELP_OUTPUT_FILES = \ + UserManual.qch \ + UserManual.qhc + +# VBOX_PDFLATEX_INTERACTION = errorstopmode - Use this when you wants to figure out build failures +# without catting the log a million times. +VBOX_PDFLATEX_INTERACTION ?= batchmode +ifeq ($(KBUILD_HOST),win) + ifndef VBOX_PDFLATEX + VBOX_PDFLATEX := $(firstword $(rsort $(wildcard $(KBUILD_DEVTOOLS)/win.x86/miktex-portable/*/miktex/bin/pdflatex.exe))) + ifneq ($(VBOX_PDFLATEX),) + VBOX_PDFLATEX_CMD = $(VBOX_PDFLATEX) -halt-on-error -interaction $(VBOX_PDFLATEX_INTERACTION) + endif + endif + ifndef VBOX_PDFLATEX + # Tell MiKTeX to automatically download packages if system wide install. + VBOX_PDFLATEX := pdflatex + VBOX_PDFLATEX_CMD = $(VBOX_PDFLATEX) -halt-on-error -interaction $(VBOX_PDFLATEX_INTERACTION) --enable-installer + endif +else + VBOX_PDFLATEX ?= pdflatex + VBOX_PDFLATEX_HALT = $(shell ( $(VBOX_PDFLATEX) -version | head -1 | grep 141592 > /dev/null ) && echo -halt-on-error ) + VBOX_PDFLATEX_CMD = pdflatex $(VBOX_PDFLATEX_HALT) -interaction $(VBOX_PDFLATEX_INTERACTION) +endif + +# Windows HTML Help Workshop compiler (stupid thing always returns an error!) +VBOX_HHC = -$(EXEC_X86_WIN32) $(VBOX_PATH_HTML_HELP_WORKSHOP)/hhc.exe + + +# Additional xsltproc options when generating +VBOX_HTMLHELP_OPTS ?= + +# SDK related globals. +VBOX_MANUAL_APIREF_TMP = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef_apiref.xml +VBOX_DOC_XIDL_SRC = $(PATH_ROOT)/src/VBox/Main/idl/VirtualBox.xidl +VBOX_DOC_XIDL_SRC_TMP = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/VirtualBox.xidl.tmp + + +# +# Targets +# + +BLDDIRS += $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/, $(VBOX_MANUAL_LANGUAGES)) + +if defined(VBOX_WITH_DOCS) && (!defined(VBOX_ONLY_BUILD) || defined(VBOX_ONLY_DOCS) || defined(VBOX_ONLY_SDK)) + if defined(VBOX_ONLY_SDK) || defined(VBOX_WITH_DOCS_SDKREF) + INSTALLS += VBox-docs-sdkref + endif + + ifdef VBOX_WITH_DOCS_HTML + INSTALLS += VBox-docs-usermanual-html + VBOX_PATH_BIN_HTML = $(PATH_STAGE_BIN)/UserManual-html.zip + else # Do not build html. + VBOX_PATH_BIN_HTML = + endif + + ifdef VBOX_WITH_DOCS_CHM + INSTALLS += VBox-docs-usermanual-chm + VBOX_PATH_BIN_CHM = $(PATH_STAGE_BIN)/VirtualBox.chm + else # Do not build chm. + VBOX_PATH_BIN_CHM = + endif + + ifdef VBOX_WITH_DOCS_QHELP + INSTALLS += VBox-docs-usermanual-qhc + INSTALLS += VBox-docs-usermanual-qch + ifdef VBOX_WITH_QT6 + USES += qt6 + QHELPGENERATOR = $(PATH_TOOL_QT6_LIBEXEC)/qhelpgenerator + else # Qt5 + USES += qt5 + QHELPGENERATOR_VERSION_MINOR = $(shell $(REDIRECT) -E QT_QPA_PLATFORM_PLUGIN_PATH=$(PATH_SDK_QT5)/plugins -- $(PATH_TOOL_QT5_BIN)/qhelpgenerator -v 2>/dev/null | $(SED) -ne 's/.*(Qt [1-9][0-9]*\.\([1-9][0-9]*\)\.[1-9][0-9]*).*$$/\1/p') + QHELPGENERATOR = $(PATH_TOOL_QT5_BIN)/$(if-expr $(QHELPGENERATOR_VERSION_MINOR) >= 12,qhelpgenerator,qcollectiongenerator) + endif + endif + ifdef VBOX_WITH_DOCS_QHELP_PACKING + VBOX_PATH_BIN_QHELP = $(PATH_STAGE_BIN)/UserManual.qch + VBOX_PATH_BIN_QHELP += $(PATH_STAGE_BIN)/UserManual.qhc + else # Do not install/pack qhelp. + VBOX_PATH_BIN_QHELP = + endif + + + ifndef VBOX_ONLY_SDK + VBOX_MANUAL_PACK += \ + $(PATH_STAGE_BIN)/UserManual.pdf \ + $(VBOX_PATH_BIN_HTML) \ + $(VBOX_PATH_BIN_CHM) \ + $(VBOX_PATH_BIN_QHELP) + INSTALLS += VBox-docs-usermanual + + ifdef VBOX_WITH_DOCS_TRANSLATIONS + INSTALLS += VBox-docs-usermanual-l10n + VBOX_MANUAL_PACK += \ + $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/UserManual_$(f).pdf) + ifdef VBOX_WITH_DOCS_CHM + INSTALLS += VBox-docs-usermanual-l10n-chm + VBOX_MANUAL_PACK += \ + $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/VirtualBox_$(f).chm) + endif + endif + endif # !VBOX_ONLY_SDK + + ifdef VBOX_WITH_DOCS_ACCESSIBILITY + INSTALLS += VBox-docs-accessibility + INSTALLS += VBox-docs-accessibility-html + endif + + ifdef VBOX_ONLY_DOCS + PACKING += $(PATH_STAGE_BIN)/VBoxDocumentation.zip + endif + + ifdef VBOX_WITH_DOCS_TRANSLATIONS + VBOX_MANUAL_LANGUAGES += $(VBOX_MANUAL_ADD_LANGUAGES) + endif + + $(foreach lang,$(VBOX_MANUAL_LANGUAGES), \ + $(eval VBOX_MANUAL_XML_FILES_GENERATED_$$(lang) := \ + $$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/$$(lang)/user_,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \ + $$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/overview_,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \ + $$(VBOX_PATH_MANUAL_OUTBASE)/$$(lang)/user_man_VBoxHeadless.xml \ + $$(VBOX_PATH_MANUAL_OUTBASE)/$$(lang)/user_man_vboximg-mount.xml \ + $$(VBOX_PATH_MANUAL_OUTBASE)/$$(lang)/user_isomakercmd-man.xml)) + + VBOX_SDKREF_XML_FILES = \ + SDKRef.xml + + VBOX_ACCESSIBILITY_XML_FILES = \ + Accessibility.xml + + + # Wildcard the images path for every supported language + $(foreach f,$(VBOX_MANUAL_LANGUAGES), \ + $(eval VBOX_MANUAL_PNG_FILES_$$(f) := $$(patsubst $$(VBOX_PATH_MANUAL_SRC)/$$(f)/%,%,$$(wildcard $$(VBOX_PATH_MANUAL_SRC)/$$(f)/images/*.png)))) + + VBOX_MANUAL_TEX_UNICODE_FILES = \ + $(wildcard $(VBOX_PATH_MANUAL_SRC)/texfiles/unicode/*) + + VBOX_MANUAL_LATEX_FILES_TARGET = \ + $(addprefix UserManual.,aux log out toc tex) + + VBOX_SDKREF_LATEX_FILES_TARGET = \ + $(addprefix SDKRef.,aux log out toc tex) + + VBOX_ACCESSIBILITY_LATEX_FILES_TARGET = \ + $(addprefix Accessibility.,aux log out toc tex) + + BLDDIRS += \ + $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/, \ + $(addsuffix /images, $(VBOX_MANUAL_LANGUAGES)) \ + $(addsuffix /html-single, $(VBOX_MANUAL_LANGUAGES)) \ + $(addsuffix /html-chunks, $(VBOX_MANUAL_LANGUAGES)) \ + $(addsuffix /qhelp, $(VBOX_MANUAL_LANGUAGES)) \ + $(addsuffix /qhelp/images, $(VBOX_MANUAL_LANGUAGES)) \ + $(addsuffix /HTMLHelp, $(VBOX_MANUAL_LANGUAGES)) \ + $(addsuffix /HTMLHelp/images, $(VBOX_MANUAL_LANGUAGES)) \ + ) + + # Explicit cleaning has some overlap with default cleaning rules, since this + # Makefile is using very complex conditionals for selectively creating + # specific files, and not everyone remembers to use the same with "kmk clean". + OTHER_CLEAN += \ + $(VBOX_XML_CATALOG) \ + $(VBOX_XML_CATALOG_DOCBOOK) \ + $(VBOX_XML_CATALOG_MANUAL) \ + $(VBOX_XML_ENTITIES) \ + $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/, \ + $(VBOX_XML_XREF_TO_TEXT) \ + $(VBOX_XML_XREF_TO_TEXT).cat \ + $(addprefix user_,$(VBOX_MANUAL_XML_REFENTRY_FILES)) \ + $(VBOX_MANUAL_XML_REFENTRY_FILES) \ + $(patsubst man_%,%.1,$(basename $(VBOX_MANUAL_XML_REFENTRY_FILES))) \ + man_VBoxHeadless.xml \ + user_man_VBoxHeadless.xml \ + man_vboximg-mount.xml \ + user_man_vboximg-mount.xml \ + isomakercmd-man.xml \ + user_isomakercmd-man.xml \ + $(VBOX_MANUAL_LATEX_FILES_TARGET) \ + $(VBOX_MANUAL_PNG_FILES_$(lang)) \ + $(notdir $(VBOX_MANUAL_TEX_UNICODE_FILES)) \ + $(addprefix HTMLHelp/,$(VBOX_MANUAL_PNG_FILES_$(lang))) \ + $(addprefix qhelp/, $(VBOX_MANUAL_PNG_FILES_$(lang))) \ + html-single/UserManual.html \ + $(addprefix qhelp/, UserManual.qhp UserManual.qhcp $(VBOX_QHELP_OUTPUT_FILES)) \ + $(addprefix HTMLHelp/, index.html go01.html) \ + $(addprefix qhelp/, index.html go01.html) \ + $(addprefix html-chunks/, index.html go01.html) \ + $(foreach n,01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 \ + ,html-chunks/ch$(n).html \ + html-chunks/re$(n).html \ + HTMLHelp/ch$(n).html \ + HTMLHelp/re$(n).html \ + $(foreach d2,0 1 2 3 4 5 6 7 8 9,$(foreach d1,0 1 2 3 4 5 6 7 8 9,HTMLHelp/ch$(n)s$(d2)$(d1).html)) \ + qhelp/ch$(n).html \ + qhelp/re$(n).html \ + $(foreach d2,0 1 2 3 4 5 6 7 8 9,$(foreach d1,0 1 2 3 4 5 6 7 8 9,qhelp/ch$(n)s$(d2)$(d1).html)) ) \ + $(foreach n,a b c \ + ,html-chunks/ap$(n).html \ + HTMLHelp/ap$(n).html \ + $(foreach s,01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20,HTMLHelp/ap$(n)s$(s).html) \ + qhelp/ap$(n).html \ + $(foreach s,01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20,qhelp/ap$(n)s$(s).html) ) \ + $(foreach n,01 02 03 04 05 \ + ,html-chunks/pr$(n).html \ + HTMLHelp/pr$(n).html \ + $(foreach s,01 02 03 04 05 06 07 08,HTMLHelp/pr$(n)s$(s).html) \ + qhelp/pr$(n).html \ + $(foreach s,01 02 03 04 05 06 07 08,qhelp/pr$(n)s$(s).html) ) \ + HTMLHelp/toc.hhc \ + HTMLHelp/htmlhelp.hhp \ + qhelp/toc.hhc \ + qhelp/htmlhelp.hhp \ + UserManual.pdf \ + VirtualBox.chm \ + $(VBOX_QHELP_OUTPUT_FILES) \ + ChangeLog.html \ + validatemanual.run \ + validateaccessibility.run \ + validatesdkref.run \ + )) \ + $(VBOX_PATH_MANUAL_OUTBASE)/titlepage-htmlhelp.xsl \ + $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/overview_,$(VBOX_MANUAL_XML_REFENTRY_FILES)) \ + $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/UserManual_$(f).pdf) \ + $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/VirtualBox_$(f).chm) \ + $(PATH_STAGE_BIN)/UserManual.pdf \ + $(PATH_STAGE_BIN)/VirtualBox.chm \ + \ + $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/, \ + $(VBOX_SDKREF_LATEX_FILES_TARGET) \ + SDKRef.pdf \ + ) \ + $(PATH_STAGE_BIN)/sdk/docs/SDKRef.pdf \ + \ + $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/, \ + $(VBOX_ACCESSIBILITY_LATEX_FILES_TARGET) \ + html-single/Accessibility.html \ + Accessibility.pdf \ + ) \ + $(PATH_STAGE_BIN)/Accessibility.html \ + $(PATH_STAGE_BIN)/Accessibility.pdf \ + \ + $(VBOX_DOC_XIDL_SRC_TMP) \ + $(VBOX_MANUAL_APIREF_TMP) + +endif # if defined(VBOX_WITH_DOCS) && (!defined(VBOX_ONLY_BUILD) || defined(VBOX_ONLY_DOCS) || defined(VBOX_ONLY_SDK)) + +# +# target for installing UserManual.pdf +# +VBox-docs-usermanual_INST = $(INST_BIN) +VBox-docs-usermanual_MODE = a+r,u+w +VBox-docs-usermanual_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.pdf + +VBox-docs-usermanual-qhc_INST = $(INST_BIN) +VBox-docs-usermanual-qhc_MODE = a+r,u+w +VBox-docs-usermanual-qhc_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/UserManual.qhc + +VBox-docs-usermanual-qch_INST = $(INST_BIN) +VBox-docs-usermanual-qch_MODE = a+r,u+w +VBox-docs-usermanual-qch_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/UserManual.qch + +# +# target for installing translated UserManual_*.pdf +# +VBox-docs-usermanual-l10n_INST = $(INST_BIN) +VBox-docs-usermanual-l10n_MODE = a+r,u+w +VBox-docs-usermanual-l10n_SOURCES = $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$(f)/UserManual.pdf=>UserManual_$(f).pdf) + +# +# target for installing the chunked HTML docs +# +VBox-docs-usermanual-html_INST = $(INST_BIN) +VBox-docs-usermanual-html_MODE = a+r,u+w +VBox-docs-usermanual-html_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.zip=>UserManual-html.zip + +# +# target for installing VirtualBox.chm +# +VBox-docs-usermanual-chm_INST = $(INST_BIN) +VBox-docs-usermanual-chm_MODE = a+r,u+w +VBox-docs-usermanual-chm_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/VirtualBox.chm + +# +# target for installing translated VirtualBox_*.chm +# +VBox-docs-usermanual-l10n-chm_INST = $(INST_BIN) +VBox-docs-usermanual-l10n-chm_MODE = a+r,u+w +VBox-docs-usermanual-l10n-chm_SOURCES = $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$(f)/VirtualBox.chm=>VirtualBox_$(f).chm) + +# +# target for installing SDKRef.pdf +# +VBox-docs-sdkref_INST = $(INST_SDK)docs/ +VBox-docs-sdkref_MODE = a+r,u+w +VBox-docs-sdkref_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.pdf + +# +# target for installing Accessibility.pdf +# +VBox-docs-accessibility_INST = $(INST_BIN) +VBox-docs-accessibility_MODE = a+r,u+w +VBox-docs-accessibility_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/Accessibility.pdf + +# +# target for installing Accessibility.html +# +VBox-docs-accessibility-html_INST = $(INST_BIN) +VBox-docs-accessibility-html_MODE = a+r,u+w +VBox-docs-accessibility-html_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/Accessibility.html + +if defined(VBOX_WITH_DOCS) && (!defined(VBOX_ONLY_BUILD) || defined(VBOX_ONLY_DOCS) || defined(VBOX_ONLY_SDK)) + + ## + # Morph man pages into manual sections. + # $(evalcall2 def_vbox_refentry_to_user_sect1) + # @param 1 Language. + # @param 2 the refentry xml base file name. + # @param 3 the full refentry xml file path. + define def_vbox_refentry_to_user_sect1 + $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/user_$(2): $(3) \ + $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-sect1.xsl \ + $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \ + $$(VBOX_XML_ENTITIES) $$(VBOX_VERSION_STAMP) | $$$$(dir $$$$@) + $$(call MSG_TOOL,xsltproc $$(notdir $$(filter %.xsl,$$^)),,$$(filter %.xml,$$^),$$@) + $$(QUIET)$$(RM) -f "$$@" + $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$@ $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-sect1.xsl $$< + endef + $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(foreach file,$(VBOX_MANUAL_XML_REFENTRY_FILES) \ +man_VBoxHeadless.xml \ +man_vboximg-mount.xml \ +, $(evalcall2 def_vbox_refentry_to_user_sect1,$(lang),$(file),$(VBOX_PATH_MANUAL_SRC)/$(lang)/$(file)))) + $(foreach lang,$(VBOX_MANUAL_LANGUAGES) \ +,$(evalcall2 def_vbox_refentry_to_user_sect1,$(lang),isomakercmd-man.xml,$(PATH_ROOT)/src/VBox/Runtime/common/fs/isomakercmd-man.xml)) + + + # Generates the VBoxManage command overview include file (shared between + # languages) from the refsynopsisdiv section of the man pages. + $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/overview_,$(VBOX_MANUAL_XML_REFENTRY_FILES)): \ + $(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-overview.xsl \ + $$(patsubst overview_%,$$(VBOX_PATH_MANUAL_SRC)/en_US/%,$$(notdir $$@)) \ + $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \ + $(VBOX_XML_ENTITIES) | $$(dir $$@) + $(call MSG_TOOL,xsltproc $(notdir $(filter %.xsl,$^)),,$(firstword $(filter %.xml,$^)),$@) + $(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) --output "$@" $< $(filter %.xml,$^) + + + + + + ########################################################################################## + # + # Shared rules for PDF generation + # + ########################################################################################## + + ifndef VBOX_OSE + # copy ucs.sty and related files + $(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/ucs.sty): + $(call MSG_L1,Copying unicode support for LaTeX) + $(QUIET)$(INSTALL_STAGING) -m0644 -- $(VBOX_MANUAL_TEX_UNICODE_FILES) "$(@D)" + endif + + # copy the PNG files. + # Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input. + define def_vbox_cp_images_pdf + local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang) + $(addprefix $$(out_dir)/,$(VBOX_MANUAL_PNG_FILES_$(lang))): \ + $$(out_dir)/% : $(VBOX_PATH_MANUAL_SRC)/$(lang)/% | $$$$(dir $$$$@) + $$(call MSG_L1,Copying temporary $$< => $$@) + $$(QUIET)$$(INSTALL_STAGING) -m0644 -- '$$<' '$$(@D)' + endef + $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_cp_images_pdf)) + + + ########################################################################################## + # + # UserManual.pdf + # + ########################################################################################## + + + # Generate PDF from LaTeX + # Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input. + define def_vbox_usermanual_tex_to_pdf + local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang) + $$(out_dir)/UserManual.pdf: \ + $$(out_dir)/UserManual.tex \ + $$(if $$(VBOX_OSE),,$$(out_dir)/ucs.sty) \ + $$(addprefix $$(out_dir)/,$$(VBOX_MANUAL_PNG_FILES_$(lang))) | $$$$(dir $$$$@) + # PDF generation via Latex: generate the .tex file + $$(call MSG_L1,pdflatex $$< (four passes) -> $$@) + $$(QUIET)$$(REDIRECT) -w+ti /dev/null -C $$(@D) -- $$(VBOX_PDFLATEX_CMD) UserManual.tex + $$(QUIET)$$(REDIRECT) -w+ti /dev/null -C $$(@D) -- $$(VBOX_PDFLATEX_CMD) UserManual.tex + $$(QUIET)$$(REDIRECT) -w+ti /dev/null -C $$(@D) -- $$(VBOX_PDFLATEX_CMD) UserManual.tex + $$(QUIET)$$(REDIRECT) -w+ti /dev/null -C $$(@D) -- $$(VBOX_PDFLATEX_CMD) UserManual.tex + $$(QUIET)$$(SED) -ne '/Warning: Hyper reference/p' $$(basename $$<).log + $$(QUIET)$$(SED) -n \ + -e '/Warning: There were \(undefined references\|multiply-defined labels\)/{p; q 1}' \ + $$(basename $$@).log + $$(call MSG_L1,Fresh LaTeX-generated PDF is now at $$@) + endef + $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_usermanual_tex_to_pdf)) + + # Generate LaTeX from XML + # Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input. + define def_vbox_usermanual_xml_to_tex + local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang) + $$(out_dir)/UserManual.tex: \ + $$(addprefix $$(VBOX_PATH_MANUAL_SRC)/$(lang)/,$$(VBOX_MANUAL_XML_FILES)) \ + $$(VBOX_MANUAL_XML_FILES_COMMON) \ + $$(VBOX_MANUAL_XML_FILES_GENERATED_$(lang)) \ + $$(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl \ + $$(if $$(VBOX_HAVE_XMLLINT),$$(out_dir)/validatemanual.run,) \ + $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \ + $$(VBOX_XML_ENTITIES) $$(MAKEFILE_CURRENT) | $$$$(dir $$$$@) + $$(call MSG_TOOL,xsltproc $$(notdir $$(filter %.xsl,$$^)),,$$(firstword $$(filter %.xml,$$^)),$$@) + $$(QUIET)$$(RM) -f $$(addprefix $$(@D)/,$$(VBOX_MANUAL_LATEX_FILES_TARGET)) + # generate TeX source from processed docbook and store it in UserManual.tex.tmp; + # pass current language to xsltproc in TARGETLANG variable + $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --stringparam TARGETLANG $(lang) \ + -o $$@.tmp $$(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl $$< + # for pretty quotes, replace " with `` or '' depending on whether it's at the start of a word; + # the \QUOTE{} was inserted by docbook2latex.xsl for all quotes _outside_ of screen sections + $$(QUIET)$$(SED) \ + -e 's|^\\QUOTE{}|\\OQ{}|g' \ + -e 's|\(\W\)\\QUOTE{}|\1\\OQ{}|g' \ + -e 's|\(\w\)\\QUOTE{}|\1\\CQ{}|g' \ + --output $$@ $$@.tmp + $$(QUIET)$$(RM) -f $$@.tmp + endef + $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_usermanual_xml_to_tex)) + + # Useful aliases + usermanual UserManual.pdf:: $(PATH_STAGE_BIN)/UserManual.pdf + + debug-usermanual: + $(MAKE) --pretty-command-printing -j1 VBOX_PDFLATEX_INTERACTION=errorstopmode $(PATH_STAGE_BIN)/UserManual.pdf + + # + # Generate rules for validating the UserManual.xml. These are invoked + # automatically at build time, but can also be manually invoked via the + # 'validatemanual' and 'validatemanual_<lang>' aliases. + # + define def_vbox_validate_xml + validatemanual_$(lang):: $$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/validatemanual.run + $$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/validatemanual.run: \ + $$(addprefix $$(VBOX_PATH_MANUAL_SRC)/$(lang)/,$$(VBOX_MANUAL_XML_FILES)) \ + $$(VBOX_MANUAL_XML_FILES_COMMON) \ + $$(VBOX_MANUAL_XML_FILES_GENERATED_$(lang)) \ + $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \ + $$(VBOX_XML_ENTITIES) $$(MAKEFILE_CURRENT) | $$$$(dir $$$$@) + $$(call MSG_L1,Validating $$<) + $$(QUIET)$$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $$(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $$< + $$(QUIET)$$(APPEND) -t "$$@" "done" + endef + $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_validate_xml)) + + + # Handy aliases. + validatemanual:: $(foreach lang,$(VBOX_MANUAL_LANGUAGES),validatemanual_$(lang)) + + + + # + # SDKRef.pdf + # + + # Replace <tt> tags in VirtualBox.xidl. + $(VBOX_DOC_XIDL_SRC_TMP): $(VBOX_DOC_XIDL_SRC) $(MAKEFILE_CURRENT) | $$(dir $$@) + $(call MSG_L1,Generating $@) + $(QUIET)$(SED) -e 's|@a \+\(\w\+\)|<tt>\1</tt>|g' \ + -e 's|@c \+\(\w\+\)|<tt>\1</tt>|g' \ + --output $@ $< + + # Generate SDKRef_apiref.xml as a docbook file excerpt that will be referenced from the SDKRef.xml. + $(VBOX_MANUAL_APIREF_TMP): $(VBOX_PATH_MANUAL_SRC)/xidl2docbook.xsl $(VBOX_DOC_XIDL_SRC_TMP) + $(call MSG_L1,Generating $@) + $(QUIET)$(VBOX_XSLTPROC) $(VBOX_XSLTPROC_OPTS) --xinclude --nonet -o $@ $< $(VBOX_DOC_XIDL_SRC_TMP) + + # Turn SDKRef.xml into LaTeX. + $(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.tex: \ + $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_SDKREF_XML_FILES)) \ + $(VBOX_MANUAL_APIREF_TMP) \ + $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl \ + $(if $(VBOX_HAVE_XMLLINT),$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatesdkref.run,) \ + $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \ + $(VBOX_XML_ENTITIES) $(MAKEFILE_CURRENT) | $$(dir $$@) + $(call MSG_TOOL,xsltproc $(notdir $(filter %.xsl,$^)),,$(firstword $(filter %.xml,$^)),$@) + $(QUIET)$(RM) -f $(addprefix $(@D/),$(VBOX_SDKREF_LATEX_FILES_TARGET)) + # generate TeX source from processed docbook and store it in SDKRef.tex.tmp + $(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) --stringparam TARGETLANG en_US \ + -o $@.tmp $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl $< + # for pretty quotes, replace " with `` or '' depending on whether it's at the start of a word; + # the \QUOTE{} was inserted by docbook2latex.xsl for all quotes _outside_ of screen sections + $(QUIET)$(SED) \ + -e 's|^\\QUOTE{}|\\OQ{}|g' \ + -e 's|\(\W\)\\QUOTE{}|\1\\OQ{}|g' \ + -e 's|\(\w\)\\QUOTE{}|\1\\CQ{}|g' \ + --output $@ $@.tmp + $(QUIET)$(RM) -f $@.tmp + + # Turn SDKRef.tex into a PDF. + $(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.pdf: \ + $(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.tex \ + $(if $(VBOX_OSE),,$(VBOX_PATH_MANUAL_OUTBASE)/en_US/ucs.sty) \ + $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US)) | $$(dir $$@) + $(call MSG_L1,pdflatex $< (three passes)) + $(QUIET)$(REDIRECT) -C $(<D) -- $(VBOX_PDFLATEX_CMD) SDKRef.tex + $(QUIET)$(REDIRECT) -C $(<D) -- $(VBOX_PDFLATEX_CMD) SDKRef.tex + $(QUIET)$(REDIRECT) -C $(<D) -- $(VBOX_PDFLATEX_CMD) SDKRef.tex + $(QUIET)$(SED) -ne '/Warning: Hyper reference/p' $(basename $<).log + $(QUIET)$(SED) -n \ + -e '/Warning: There were \(undefined references\|multiply-defined labels\)/{p; q 1}' \ + $(basename $<).log + $(call MSG_L1,Fresh LaTeX-generated PDF is now at $@) + + # Validating SDKRef.xml. It is invoked automatically at build time, + # but can also be manually invoked via the 'validate-sdkref' alias. + $(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatesdkref.run: \ + $(VBOX_PATH_MANUAL_SRC)/en_US/SDKRef.xml \ + $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_SDKREF_XML_FILES)) \ + $(VBOX_MANUAL_APIREF_TMP) \ + $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \ + $(VBOX_XML_ENTITIES) $(MAKEFILE_CURRENT) | $$(dir $$@) + $(call MSG_L1,Validating $<) + $(QUIET)$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $< + $(QUIET)$(APPEND) -t "$@" "done" + + + # Handy aliases. + validate-sdkref:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatesdkref.run + sdkref:: $(PATH_STAGE_BIN)/sdk/docs/SDKRef.pdf + + + + # + # Accessibility.pdf + # + + # Turn Accessibility.xml into LaTeX. + $(VBOX_PATH_MANUAL_OUTBASE)/en_US/Accessibility.tex: \ + $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_ACCESSIBILITY_XML_FILES)) \ + $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl \ + $(if $(VBOX_HAVE_XMLLINT),$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validateaccessibility.run,) \ + $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \ + $(VBOX_XML_ENTITIES) $(MAKEFILE_CURRENT) | $$(dir $$@) + $(call MSG_TOOL,xsltproc $(notdir $(filter %.xsl,$^)),,$(firstword $(filter %.xml,$^)),$@) + $(QUIET)$(RM) -f $(addprefix $(@D/),$(VBOX_ACCESSIBILITY_LATEX_FILES_TARGET)) + # generate TeX source from processed docbook and store it in Accessibility.tex.tmp + $(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) --stringparam TARGETLANG en_US \ + -o $@.tmp $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl $< + # for pretty quotes, replace " with `` or '' depending on whether it's at the start of a word; + # the \QUOTE{} was inserted by docbook2latex.xsl for all quotes _outside_ of screen sections + $(QUIET)$(SED) \ + -e 's|^\\QUOTE{}|\\OQ{}|g' \ + -e 's|\(\W\)\\QUOTE{}|\1\\OQ{}|g' \ + -e 's|\(\w\)\\QUOTE{}|\1\\CQ{}|g' \ + --output $@ $@.tmp + $(QUIET)$(RM) -f $@.tmp + + # Turn Accessibility.tex into a PDF. + $(VBOX_PATH_MANUAL_OUTBASE)/en_US/Accessibility.pdf: \ + $(VBOX_PATH_MANUAL_OUTBASE)/en_US/Accessibility.tex \ + $(if $(VBOX_OSE),,$(VBOX_PATH_MANUAL_OUTBASE)/en_US/ucs.sty) \ + $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US)) | $$(dir $$@) + $(call MSG_L1,pdflatex $< (three passes)) + $(QUIET)$(REDIRECT) -C $(<D) -- $(VBOX_PDFLATEX_CMD) Accessibility.tex + $(QUIET)$(REDIRECT) -C $(<D) -- $(VBOX_PDFLATEX_CMD) Accessibility.tex + $(QUIET)$(REDIRECT) -C $(<D) -- $(VBOX_PDFLATEX_CMD) Accessibility.tex + $(QUIET)$(SED) -ne '/Warning: Hyper reference/p' $(basename $<).log + $(QUIET)$(SED) -n \ + -e '/Warning: There were \(undefined references\|multiply-defined labels\)/{p; q 1}' \ + $(basename $<).log + $(call MSG_L1,Fresh LaTeX-generated PDF is now at $@) + + $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/Accessibility.html: \ + $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_ACCESSIBILITY_XML_FILES)) \ + $(VBOX_DOCBOOK_HTML_ONE_PAGE_FORMATCFG) \ + $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \ + $(VBOX_XML_ENTITIES) | $$(dir $$@) + $(call MSG_TOOL,xsltproc $(notdir $(firstword $(filter %.xsl,$^))),,$(firstword $(filter %.xml,$^)),$@) + $(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) \ + --output $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/Accessibility.html \ + $(VBOX_PATH_MANUAL_SRC)/docbook-html-one-page-formatcfg.xsl \ + $< + + # Validating Accessibility.xml. It is invoked automatically at build time, + # but can also be manually invoked via the 'validate-accessibility' alias. + $(VBOX_PATH_MANUAL_OUTBASE)/en_US/validateaccessibility.run: \ + $(VBOX_PATH_MANUAL_SRC)/en_US/Accessibility.xml \ + $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_ACCESSIBILITY_XML_FILES)) \ + $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \ + $(VBOX_XML_ENTITIES) $(MAKEFILE_CURRENT) | $$(dir $$@) + $(call MSG_L1,Validating $<) + $(QUIET)$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $< + $(QUIET)$(APPEND) -t "$@" "done" + + + # Handy aliases. + validate-accessibility:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/validateaccessibility.run + accessibility:: $(PATH_STAGE_BIN)/Accessibility.pdf + accessibility-html:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/Accessibility.html + + + # A few things which are shared between htmlhelp and qhelp docs. + VBOX_DOCBOOK_HTMLHELP_FORMATCFG = \ + $(VBOX_PATH_MANUAL_SRC)/docbook-htmlhelp-formatcfg.xsl \ + $(VBOX_PATH_MANUAL_SRC)/common-formatcfg.xsl \ + $(VBOX_PATH_MANUAL_SRC)/common-html-formatcfg.xsl + + # Prepare the XSL file for our title page, htmlhelp and qhelp variant. + $(VBOX_PATH_MANUAL_OUTBASE)/titlepage-htmlhelp.xsl: \ + $(VBOX_PATH_MANUAL_SRC)/titlepage-htmlhelp.xml $(MAKEFILE_CURRENT) | $$(dir $$@) + $(call MSG_L1,xsltproc $<) + $(QUIET)$(RM) -f $@.tmp $@ + $(QUIET)$(VBOX_XSLTPROC) --xinclude --nonet -o $@.tmp $(VBOX_PATH_DOCBOOK)/template/titlepage.xsl $< + $(QUIET)$(MV) -f $@.tmp $@ + + + ifdef VBOX_WITH_DOCS_CHM + # + # VirtualBox.chm + # + # We first generate a .hhp help source file from the preprocessed + # DocBook XML files, as defined above, then feed that into the + # Microsoft Help Compiler. + + # Generate CHM from HHP + # Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input. + define def_vbox_usermanual_hhp_to_chm + local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang) + $$(out_dir)/VirtualBox.chm: \ + $$(out_dir)/HTMLHelp/htmlhelp.hhp \ + $$(addprefix $$(out_dir)/HTMLHelp/,$$(VBOX_MANUAL_PNG_FILES_$(lang))) \ + | $$$$(dir $$$$@) + $$(call MSG_L1,hhc $$<,=> $$@) + $$(QUIET)$$(RM) -f $$@ + $$(QUIET)$$(VBOX_HHC) $$(subst /,\\,$$<) + $$(call MSG_L1,Fresh CHM is now at $$@) + endef + $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_usermanual_hhp_to_chm)) + + # Generate HHP from XML + # Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input. + define def_vbox_usermanual_xml_to_hhp + local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang) + $$(out_dir)/HTMLHelp/htmlhelp.hhp: \ + $$(addprefix $$(VBOX_PATH_MANUAL_SRC)/$(lang)/,$$(VBOX_MANUAL_XML_FILES)) \ + $$(VBOX_MANUAL_XML_FILES_COMMON) \ + $$(VBOX_MANUAL_XML_FILES_GENERATED_$(lang)) \ + $$(VBOX_DOCBOOK_HTMLHELP_FORMATCFG) \ + $$(VBOX_PATH_MANUAL_OUTBASE)/titlepage-htmlhelp.xsl \ + $$(if $$(VBOX_HAVE_XMLLINT),$$(out_dir)/validatemanual.run,) \ + $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \ + $$(VBOX_XML_ENTITIES) | $$$$(dir $$$$@) + $$(call MSG_TOOL,xsltproc $$(notdir $$(firstword $$(filter %.xsl,$$^))),,$$(firstword $$(filter %.xml,$$^)),$$@) + $$(QUIET)$$(RM) -f $$@ + $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$(@D)/ \ + --stringparam htmlhelp.chm \ + $$(subst /,\\,$$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/VirtualBox.chm) \ + $$(HTMLHELPOPTS) $$(VBOX_PATH_MANUAL_SRC)/docbook-htmlhelp-formatcfg.xsl \ + $$< + endef + $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_usermanual_xml_to_hhp)) + + # copy the PNG files. + # Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input. + define def_vbox_cp_images_htmlhelp + local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/HTMLHelp + $(addprefix $$(out_dir)/,$(VBOX_MANUAL_PNG_FILES_$(lang))): \ + $$(out_dir)/% : $(VBOX_PATH_MANUAL_SRC)/$(lang)/% | $$$$(dir $$$$@) + $$(call MSG_L1,Copying temporary $$< => $$@) + $$(QUIET)$$(INSTALL_STAGING) -m0644 -- '$$<' '$$(@D)' + endef + $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(eval $(def_vbox_cp_images_htmlhelp))) + + endif # VBOX_WITH_DOCS_CHM + + + # Packing the docs into a zip file + $(PATH_STAGE_BIN)/VBoxDocumentation.zip: $(VBOX_MANUAL_PACK) + $(call MSG_L1,Packing documentation $@) + $(QUIET)$(RM) -f $@ + $(QUIET)$(REDIRECT) -C $(PATH_STAGE_BIN) -- $(VBOX_ZIP) -9 $@ $(notdir $^) + + + ########################################################################################## + # + # UserManual.html + # + ########################################################################################## + VBOX_DOCBOOK_HTML_ONE_PAGE_FORMATCFG = \ + $(VBOX_PATH_MANUAL_SRC)/docbook-html-one-page-formatcfg.xsl \ + $(VBOX_PATH_MANUAL_SRC)/common-formatcfg.xsl \ + $(VBOX_PATH_MANUAL_SRC)/common-html-formatcfg.xsl + + $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html: \ + $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_MANUAL_XML_FILES)) \ + $(VBOX_MANUAL_XML_FILES_COMMON) \ + $(VBOX_MANUAL_XML_FILES_GENERATED_en_US) \ + $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US)) \ + $(VBOX_DOCBOOK_HTML_ONE_PAGE_FORMATCFG) \ + $(if $(VBOX_HAVE_XMLLINT),$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatemanual.run,) \ + $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \ + $(VBOX_XML_ENTITIES) | $$(dir $$@) + $(call MSG_TOOL,xsltproc $(notdir $(firstword $(filter %.xsl,$^))),,$(firstword $(filter %.xml,$^)),$@) + $(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) \ + --output $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html \ + $(VBOX_PATH_MANUAL_SRC)/docbook-html-one-page-formatcfg.xsl \ + $< + + VBOX_DOCBOOK_HTML_CHUNKS_FORMATCFG = \ + $(VBOX_PATH_MANUAL_SRC)/docbook-html-chunks-formatcfg.xsl \ + $(VBOX_PATH_MANUAL_SRC)/common-formatcfg.xsl \ + $(VBOX_PATH_MANUAL_SRC)/common-html-formatcfg.xsl + + $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html: \ + $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_MANUAL_XML_FILES)) \ + $(VBOX_MANUAL_XML_FILES_COMMON) \ + $(VBOX_MANUAL_XML_FILES_GENERATED_en_US) \ + $(VBOX_DOCBOOK_HTML_CHUNKS_FORMATCFG) \ + $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US)) \ + $(if $(VBOX_HAVE_XMLLINT),$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatemanual.run,) \ + $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \ + $(VBOX_XML_ENTITIES) | $$(dir $$@) + $(call MSG_TOOL,xsltproc $(notdir $(firstword $(filter %.xsl,$^))),,$(firstword $(filter %.xml,$^)),$@) + $(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) \ + --output $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html \ + --stringparam chunk.section.depth 0 \ + $(VBOX_PATH_MANUAL_SRC)/docbook-html-chunks-formatcfg.xsl \ + $< + + $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.zip: \ + $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html \ + $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html \ + $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US)) + $(call MSG_L1,Packing documentation $@) + $(QUIET)$(RM) -f $@ + $(QUIET)$(REDIRECT) -C $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ -- $(VBOX_ZIP) \ + -9 -r $@ html-single html-chunks $(VBOX_MANUAL_PNG_FILES_en_US) + + html:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html + html:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html + qhelp:: $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/, $(VBOX_QHELP_OUTPUT_FILES)) + html-zip:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.zip + + # + # ChangeLog.html + # + # This XSLT rule formats en_US/user_ChangeLog.xml (which includes the actual change log + # contained in user_ChangeLogImpl.xml) as a standalone HTML file. + # + $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ChangeLog.html: \ + $(VBOX_PATH_MANUAL_SRC)/en_US/docbook-changelog-formatcfg.xsl \ + $(VBOX_PATH_MANUAL_OUTBASE)/en_US/user_ChangeLog.xml \ + $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \ + $(VBOX_XML_ENTITIES) | $$(dir $$@) + $(call MSG_TOOL,xsltproc $(notdir $(firstword $(filter %.xsl,$^))),,$(firstword $(filter %.xml,$^)),$@) + $(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) --output "$@" "$<" $(filter %.xml,$^) + $(call MSG_L1,Fresh ChangeLog.html is now at $@) + + cl-html:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ChangeLog.html + + + +endif # if defined(VBOX_WITH_DOCS) && (!defined(VBOX_ONLY_BUILD) || defined(VBOX_ONLY_DOCS) || defined(VBOX_ONLY_SDK)) + + +# +# VBoxManage man pages (parts also required by VBoxManage built-in help). +# + +## +# Emits rules for preprocessing refentry sources (applying remarks element), +# and for producing the actual man pages. +# $(evalcall2 def_vbox_refentry_to_manpage) +# @param 1 The language +# @param 2 The file name (no path). +define def_vbox_refentry_to_manpage + $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$(2): \ + $$(VBOX_PATH_MANUAL_SRC)/$(1)/$(2) \ + $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl \ + $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$$(VBOX_XML_XREF_TO_TEXT) \ + $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \ + $$(VBOX_XML_ENTITIES) $$(VBOX_VERSION_STAMP) | $$$$(dir $$$$@) + $$(call MSG_TOOL,xsltproc $$(notdir $$(firstword $$(filter %.xsl,$$^))),,$$(firstword $$(filter %.xml,$$^)),$$@) + $$(QUIET)$$(RM) -f "$$@" + $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$@ \ + $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl $$< + $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$@.tmp $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$$(VBOX_XML_XREF_TO_TEXT) $$@ + $$(QUIET)$$(MV) -f -- "$$@.tmp" "$$@" + if defined(VBOX_HAVE_XMLLINT) + $$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $$(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $$@ + endif + + $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$(patsubst man_%,%.1,$(basename $(2))): \ + $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$(2) \ + $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage.xsl \ + $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \ + $$(VBOX_XML_ENTITIES) $$(VBOX_VERSION_STAMP) | $$$$(dir $$$$@) + $$(call MSG_TOOL,xsltproc $$(notdir $$(firstword $$(filter %.xsl,$$^))),,$$(firstword $$(filter %.xml,$$^)),$$@) + $$(QUIET)$$(RM) -f "$$@" + $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --maxdepth 6000 --output $$@ $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage.xsl $$< +endef +$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(foreach file,$(VBOX_MANUAL_XML_REFENTRY_FILES) \ +, $(evalcall2 def_vbox_refentry_to_manpage,$(lang),$(file)))) + + +ifdef VBOX_WITH_DOCS_QHELP + # + # VirtualBox.qch/VirtualBox.qhc + # + # We first generate a .hhp help source file from the preprocessed + # DocBook XML files, as defined above, then feed that into a converter + # creating the suitable input for creating a QHelp collection file. + + # Generate QCH from QHelp source + # Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input. + define def_vbox_usermanual_qhp_to_qch + local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang) + $$(out_dir)/qhelp/UserManual.qch + \ + $$(out_dir)/qhelp/UserManual.qhc: \ + $$(out_dir)/qhelp/UserManual.qhcp \ + $$(out_dir)/qhelp/UserManual.qhp \ + $$(addprefix $$(out_dir)/qhelp/,$$(VBOX_MANUAL_PNG_FILES_$(lang))) \ + | $$$$(dir $$$$@) + $$(call MSG_L1,$$(notdir $$(QHELPGENERATOR)) $$<,=> $$@) + $$(QUIET)$$(RM) -f $$@ + $$(QUIET)$$(REDIRECT) -E QT_QPA_PLATFORM_PLUGIN_PATH=$$(PATH_SDK_QT5)/plugins -- $$(QHELPGENERATOR) $$< + $$(call MSG_L1,Fresh QCH is now at $$@) + endef + $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_usermanual_qhp_to_qch)) + + # Generate QHP from HHP for QHelp + # Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input. + define def_vbox_usermanual_hhp_qhelp_to_qhp + local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang) + $$(out_dir)/qhelp/UserManual.qhp: \ + $$(out_dir)/qhelp/htmlhelp.hhp \ + $$(addprefix $$(out_dir)/qhelp/,$$(VBOX_MANUAL_PNG_FILES_$(lang))) \ + | $$$$(dir $$$$@) + $$(call MSG_L1,htmlhelp-qthelp.py $$<,=> $$@) + $$(QUIET)$$(RM) -f $$@ + $$(QUIET)$$(VBOX_BLD_PYTHON) $$(VBOX_PATH_MANUAL_SRC)/htmlhelp-qthelp.py -d $$(<D) -o $$@ + endef + $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_usermanual_hhp_qhelp_to_qhp)) + + # Generate HHP for QHelp from XML + # Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input. + define def_vbox_usermanual_xml_to_hhp_qhelp + local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang) + $$(out_dir)/qhelp/htmlhelp.hhp: \ + $$(addprefix $$(VBOX_PATH_MANUAL_SRC)/$(lang)/,$$(VBOX_MANUAL_XML_FILES)) \ + $$(VBOX_MANUAL_XML_FILES_COMMON) \ + $$(VBOX_MANUAL_XML_FILES_GENERATED_$(lang)) \ + $$(VBOX_DOCBOOK_HTMLHELP_FORMATCFG) \ + $$(VBOX_PATH_MANUAL_OUTBASE)/titlepage-htmlhelp.xsl \ + $$(if $$(VBOX_HAVE_XMLLINT),$$(out_dir)/validatemanual.run,) \ + $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \ + $$(VBOX_XML_ENTITIES) | $$$$(dir $$$$@) + $$(call MSG_TOOL,xsltproc $$(notdir $$(firstword $$(filter %.xsl,$$^))),,$$(firstword $$(filter %.xml,$$^)),$$@) + $$(QUIET)$$(RM) -f $$@ + $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$(@D)/ \ + --stringparam htmlhelp.chm \ + $$(subst /,\\,$$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/VirtualBox.chm) \ + $$(HTMLHELPOPTS) $$(VBOX_PATH_MANUAL_SRC)/docbook-htmlhelp-formatcfg.xsl \ + $$< + endef + $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_usermanual_xml_to_hhp_qhelp)) + + # copy the qhcp file. + define def_vbox_cp_qhcp + local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/qhelp + $$(out_dir)/UserManual.qhcp: \ + $$(out_dir)/% : $(VBOX_PATH_MANUAL_SRC)/% | $$$$(dir $$$$@) + $$(QUIET)$$(INSTALL_STAGING) -m0644 -- '$$<' '$$(@D)' + endef + $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(eval $(def_vbox_cp_qhcp))) + + # copy the PNG files. + # Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input. + define def_vbox_cp_images_qhelp + local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/qhelp + $(addprefix $$(out_dir)/,$(VBOX_MANUAL_PNG_FILES_$(lang))): \ + $$(out_dir)/% : $(VBOX_PATH_MANUAL_SRC)/$(lang)/% | $$$$(dir $$$$@) + $$(call MSG_L1,Copying temporary $$< => $$@) + $$(QUIET)$$(INSTALL_STAGING) -m0644 -- '$$<' '$$(@D)' + endef + $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(eval $(def_vbox_cp_images_qhelp))) + +endif # VBOX_WITH_DOCS_QHELP + + +# Handy aliases. +validate-manpages:: $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_XML_REFENTRY_FILES)) +man-experiment:: $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(foreach file,$(VBOX_MANUAL_XML_REFENTRY_FILES) \ + ,$$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/$(patsubst man_%,%.1,$(basename $(file))))) + +# +# Manually updating the DHCP option list taken from VirtualBox.xidl +# +dhcpoptions: $(PATH_ROOT)/doc/manual/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xsl \ + $(PATH_ROOT)/src/VBox/Main/idl/VirtualBox.xidl + $(call VBOX_XSLTPROC) --output "$(PATH_ROOT)/doc/manual/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xml" $+ + + +include $(FILE_KBUILD_SUB_FOOTER) + diff --git a/doc/manual/UserManual.qhcp b/doc/manual/UserManual.qhcp new file mode 100644 index 00000000..05643024 --- /dev/null +++ b/doc/manual/UserManual.qhcp @@ -0,0 +1,55 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + UserManul.qhcp: + UserManual qt help configuration file. XML to configure qt help project. +--> +<!-- + Copyright (C) 2018-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<QHelpCollectionProject version="1.0"> + <assistant> + <title>Virtual Box</title> + <!-- <applicationIcon>images/handbook.png</applicationIcon> --> + <cacheDirectory>QtProject/vbox</cacheDirectory> + <startPage>qthelp://org.virtualbox/manual/UserManual.xhtml</startPage> + <aboutMenuText> + <text>VirtualBox</text> + </aboutMenuText> + <!-- <aboutDialog> --> + <!-- <file>about.txt</file> --> + <!-- <icon>images/icon.png</icon> --> + <!-- </aboutDialog> --> + <enableDocumentationManager>false</enableDocumentationManager> + <enableAddressBar>true</enableAddressBar> + <enableFilterFunctionality>false</enableFilterFunctionality> + </assistant> + <docFiles> + <generate> + <file> + <input>UserManual.qhp</input> + <output>UserManual.qch</output> + </file> + </generate> + <register> + <file>UserManual.qch</file> + </register> + </docFiles> +</QHelpCollectionProject> diff --git a/doc/manual/common-formatcfg.xsl b/doc/manual/common-formatcfg.xsl new file mode 100644 index 00000000..3db289bb --- /dev/null +++ b/doc/manual/common-formatcfg.xsl @@ -0,0 +1,169 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> + +<!-- General formatting settings. --> +<xsl:variable name="section.autolabel">1</xsl:variable> +<xsl:variable name="section.label.includes.component.label">1</xsl:variable> +<xsl:attribute-set name="monospace.properties"> + <xsl:attribute name="font-size">90%</xsl:attribute> +</xsl:attribute-set> +<xsl:param name="draft.mode" select="'no'"/> + +<!-- Shift down section sizes one magstep. --> +<xsl:attribute-set name="section.title.level1.properties"> + <xsl:attribute name="font-size"> + <xsl:value-of select="$body.font.master * 1.728"></xsl:value-of> + <xsl:text>pt</xsl:text> + </xsl:attribute> +</xsl:attribute-set> +<xsl:attribute-set name="section.title.level2.properties"> + <xsl:attribute name="font-size"> + <xsl:value-of select="$body.font.master * 1.44"></xsl:value-of> + <xsl:text>pt</xsl:text> + </xsl:attribute> +</xsl:attribute-set> +<xsl:attribute-set name="section.title.level3.properties"> + <xsl:attribute name="font-size"> + <xsl:value-of select="$body.font.master * 1.2"></xsl:value-of> + <xsl:text>pt</xsl:text> + </xsl:attribute> +</xsl:attribute-set> +<xsl:attribute-set name="section.title.level4.properties"> + <xsl:attribute name="font-size"> + <xsl:value-of select="$body.font.master"></xsl:value-of> + <xsl:text>pt</xsl:text> + </xsl:attribute> +</xsl:attribute-set> +<xsl:attribute-set name="section.title.level5.properties"> + <xsl:attribute name="font-size"> + <xsl:value-of select="$body.font.master"></xsl:value-of> + <xsl:text>pt</xsl:text> + </xsl:attribute> +</xsl:attribute-set> +<xsl:attribute-set name="section.title.level6.properties"> + <xsl:attribute name="font-size"> + <xsl:value-of select="$body.font.master"></xsl:value-of> + <xsl:text>pt</xsl:text> + </xsl:attribute> +</xsl:attribute-set> + +<!-- Shift down chapter font size one magstep. --> +<xsl:attribute-set name="component.title.properties"> + <xsl:attribute name="font-size"> + <xsl:value-of select="$body.font.master * 2.0736"></xsl:value-of> + <xsl:text>pt</xsl:text> + </xsl:attribute> +</xsl:attribute-set> + +<!-- command synopsis --> +<xsl:variable name="arg.choice.opt.open.str">[</xsl:variable> +<xsl:variable name="arg.choice.opt.close.str">]</xsl:variable> +<xsl:variable name="arg.choice.req.open.str"><</xsl:variable> +<xsl:variable name="arg.choice.req.close.str">></xsl:variable> +<xsl:variable name="arg.choice.plain.open.str"><xsl:text> </xsl:text></xsl:variable> +<xsl:variable name="arg.choice.plain.close.str"><xsl:text> </xsl:text></xsl:variable> +<xsl:variable name="arg.choice.def.open.str">[</xsl:variable> +<xsl:variable name="arg.choice.def.close.str">]</xsl:variable> +<xsl:variable name="arg.rep.repeat.str">...</xsl:variable> +<xsl:variable name="arg.rep.norepeat.str"></xsl:variable> +<xsl:variable name="arg.rep.def.str"></xsl:variable> +<xsl:variable name="arg.or.sep"> | </xsl:variable> +<xsl:variable name="cmdsynopsis.hanging.indent">4pi</xsl:variable> + +<!-- + Make sure that sections inside the Preface are not numbered. + --> +<xsl:template match="preface/sect1" mode="object.title.template"> + <xsl:call-template name="gentext.template"> + <xsl:with-param name="context" select="'title-unnumbered'"/> + <xsl:with-param name="name"> + <xsl:call-template name="xpath.location"/> + </xsl:with-param> + </xsl:call-template> +</xsl:template> + +<!-- + refentry related layout tweaks. + + Note! While we could save us all this work by using refsect1..3 and + refsynopsisdiv docbook-refentry-to-manual-sect1.xsl, we'd like to have + a valid XML document and thus do do some extra markup using the role + and condition attributes. We catch some of it here. But the XSLT + for specific targets (html, latex, etc) have a few more tweaks + related to this. + + The @role has only one special trick 'not-in-toc' that excludes sections + like 'Synopsis' and 'Description' from the TOCs. + + The @condition records the original refentry element name, i.e. it will + have values like refentry, refsynopsisdiv, refsect1, refsect2 and refsect3. + --> + +<!-- This removes the not-in-toc bits from the toc. --> +<xsl:template match="sect2[@role = 'not-in-toc']" mode="toc" /> +<xsl:template match="sect3[@role = 'not-in-toc']" mode="toc" /> +<xsl:template match="sect4[@role = 'not-in-toc']" mode="toc" /> +<xsl:template match="sect5[@role = 'not-in-toc']" mode="toc" /> +<xsl:template match="section[@role = 'not-in-toc']" mode="toc" /> +<xsl:template match="simplesect[@role = 'not-in-toc']" mode="toc" /> + +<!-- This removes unnecessary <dd><dl> stuff caused by the above. --> +<xsl:template match="sect1[sect2/@role = 'not-in-toc']" mode="toc"> + <xsl:param name="toc-context" select="."/> + <xsl:call-template name="subtoc"> + <xsl:with-param name="toc-context" select="$toc-context"/> + <xsl:with-param name="nodes" select="sect2[@role != 'not-in-toc'] | bridgehead[$bridgehead.in.toc != 0]"/> + </xsl:call-template> +</xsl:template> + +<xsl:template match="sect2[sect3/@role = 'not-in-toc']" mode="toc"> + <xsl:param name="toc-context" select="."/> + <xsl:call-template name="subtoc"> + <xsl:with-param name="toc-context" select="$toc-context"/> + <xsl:with-param name="nodes" select="sect3[@role != 'not-in-toc'] | bridgehead[$bridgehead.in.toc != 0]"/> + </xsl:call-template> +</xsl:template> + +<!-- This make the refsect* and refsynopsisdiv unnumbered like the default refentry rendering. --> +<xsl:template match="sect2[@condition = 'refsynopsisdiv'] + | sect2[starts-with(@condition, 'refsect')] + | sect3[starts-with(@condition, 'refsect')] + | sect4[starts-with(@condition, 'refsect')] + | sect5[starts-with(@condition, 'refsect')] + | section[starts-with(@condition, 'refsect')] + | simplesect[starts-with(@condition, 'refsect')]" + mode="object.title.template" + > + <xsl:call-template name="gentext.template"> + <xsl:with-param name="context" select="'title-unnumbered'"/> + <xsl:with-param name="name"> + <xsl:call-template name="xpath.location"/> + </xsl:with-param> + </xsl:call-template> +</xsl:template> + + +</xsl:stylesheet> diff --git a/doc/manual/common-html-formatcfg.xsl b/doc/manual/common-html-formatcfg.xsl new file mode 100644 index 00000000..b2147434 --- /dev/null +++ b/doc/manual/common-html-formatcfg.xsl @@ -0,0 +1,197 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> + +<!-- Must strip spaces in 'arg' elements too, we'll get extra spaces when + using 'replaceable'. Adding option too, just in case. --> +<xsl:strip-space elements="arg option"/> + +<!-- Our hand written css styling. --> +<xsl:template name="user.head.content"> + <style type="text/css"> + <xsl:comment> + body + { + font-family: Verdana, Sans-serif, Arial, 'Trebuchet MS', 'Times New Roman'; + font-size: small; + } + h2.title + { + font-family: Verdana, Sans-serif, Arial, 'Trebuchet MS', 'Times New Roman'; + margin: 5px 0 0; + padding: 1px 5px 1px; + border: 1px solid #6b89d4; + -moz-border-radius: 0.3em; + background: #e6edff; + } + .titlepage + { + text-align: center; + } + .refsynopsisdiv, .refsect1, .refsect2, .refsect3 + { + text-align: left; + } + .warning + { + padding: 5px; + border: 1px solid #ff0011; + -moz-border-radius: 0.3em; + background: #ffbbbb; + } + .warning .title { margin: 0px 0px 5px 0px; } + .warning p { margin: 1px; } + .note + { + padding: 1px 5px 1px; + border: 1px solid #84c43b; + -moz-border-radius: 0.3em; + background: #d7e9a7; + } + .note .title { margin: 0px 0px 5px 0px; } + .note p { margin: 1px; } + .cmdsynopsis + { + font-family: monospace; + } + .refsynopsisdiv > .cmdsynopsis p, .refsect1 > .cmdsynopsis p, + .refsynopsisdiv .sect2 > .cmdsynopsis p, .refsect1 .sect2 > .cmdsynopsis p + { + margin-top: 0px; + margin-bottom: 0px; + } + .cmdsynopsis p + { + padding-left: 3.4em; + text-indent: -2.2em; + } + p.nextcommand + { + margin-top: 0px; + margin-bottom: 0px; + } + p.lastcommand + { + margin-top: 0px; + } + .refentry * h3 + { + font-size: large; + } + .refentry * h4 + { + font-size: larger; + } + .refentry * h5 + { + font-size: larger; + } + + </xsl:comment> + </style> +</xsl:template> + + +<!-- Ignore/skip the remark that the command overview inclusion file + uses as the root element. --> +<xsl:template match="remark[@role='VBoxManage-overview']"> + <xsl:apply-templates select="node()"/> +</xsl:template> + + +<!-- This is for allow special CSS rules to apply to the refsect stuff. --> +<xsl:template match="sect2[ @role = 'not-in-toc']/title + | sect3[ @role = 'not-in-toc']/title + | sect4[ @role = 'not-in-toc']/title + | sect5[ @role = 'not-in-toc']/title + | section[ @role = 'not-in-toc']/title + | simplesect[@role = 'not-in-toc']/title + | sect1[ @condition = 'refentry']/title + | sect2[ @condition = 'refentry']/title + | sect1[ starts-with(@condition, 'refsect')]/title + | sect2[ starts-with(@condition, 'refsect')]/title + | sect3[ starts-with(@condition, 'refsect')]/title + | sect4[ starts-with(@condition, 'refsect')]/title + | sect5[ starts-with(@condition, 'refsect')]/title + | section[ starts-with(@condition, 'refsect')]/title + | simplesect[starts-with(@condition, 'refsect')]/title +" mode="titlepage.mode"> + <xsl:element name="div"> + <xsl:attribute name="class"> + <xsl:value-of select="../@role"/> + <xsl:if test="../@role and ../@condition"> + <xsl:text> </xsl:text> + </xsl:if> + <xsl:value-of select="../@condition"/> + </xsl:attribute> + <xsl:apply-imports/> + </xsl:element> +</xsl:template> + +<xsl:template match="sect2[ @role = 'not-in-toc'] + | sect3[ @role = 'not-in-toc'] + | sect4[ @role = 'not-in-toc'] + | sect5[ @role = 'not-in-toc'] + | section[ @role = 'not-in-toc'] + | simplesect[@role = 'not-in-toc'] + | sect1[ @condition = 'refentry'] + | sect2[ @condition = 'refentry'] + | sect1[ starts-with(@condition, 'refsect')] + | sect2[ starts-with(@condition, 'refsect')] + | sect3[ starts-with(@condition, 'refsect')] + | sect4[ starts-with(@condition, 'refsect')] + | sect5[ starts-with(@condition, 'refsect')] + | section[ starts-with(@condition, 'refsect')] + | simplesect[starts-with(@condition, 'refsect')]" > + <xsl:element name="div"> + <xsl:attribute name="class"> + <xsl:value-of select="@role"/> + <xsl:if test="@role and @condition"> + <xsl:text> </xsl:text> + </xsl:if> + <xsl:value-of select="@condition"/> + </xsl:attribute> + <xsl:apply-imports/> + </xsl:element> +</xsl:template> + +<!-- To use CSS to correctly insert hanging indent when soft wrapping and + <sbr>'ing a synopsis, we must place each command in its own <p>. The default + is to must issue a <br /> before each <command>, except the first one. + Note! This is a bit ugly as we're going contrary to the grain of XSLT here + starting with an closing . --> +<xsl:template match="cmdsynopsis/command"> + <xsl:text disable-output-escaping="yes"><![CDATA[</p><p class="nextcommand">]]></xsl:text> + <xsl:call-template name="inline.monoseq"/> + <xsl:text> </xsl:text> +</xsl:template> +<xsl:template match="cmdsynopsis/command[last()]"> + <xsl:text disable-output-escaping="yes"><![CDATA[</p><p class="lastcommand">]]></xsl:text> + <xsl:call-template name="inline.monoseq"/> + <xsl:text> </xsl:text> +</xsl:template> + +</xsl:stylesheet> + diff --git a/doc/manual/docbook-changelog-formatcfg.xsl b/doc/manual/docbook-changelog-formatcfg.xsl new file mode 100644 index 00000000..fd960594 --- /dev/null +++ b/doc/manual/docbook-changelog-formatcfg.xsl @@ -0,0 +1,103 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> + +<!-- Single html file template --> +<xsl:import href="html/docbook.xsl"/> +<xsl:import href="common-formatcfg.xsl"/> + +<!-- Adjust some params --> +<!-- +<xsl:param name="draft.mode" select="'no'"/> +<xsl:param name="generate.toc">book nop</xsl:param> +<xsl:param name="generate.index" select="0"></xsl:param> +<xsl:param name="suppress.navigation" select="1"></xsl:param> +<xsl:param name="header.rule" select="0"></xsl:param> +<xsl:param name="abstract.notitle.enabled" select="0"></xsl:param> +<xsl:param name="footer.rule" select="0"></xsl:param> +<xsl:param name="css.decoration" select="1"></xsl:param> +<xsl:param name="html.cleanup" select="1"></xsl:param> +<xsl:param name="css.decoration" select="1"></xsl:param> +--> + +<!-- Our hand written css styling --> +<xsl:template name="user.head.content"> + <style type="text/css"> + <xsl:comment> + <!-- + body + { + height: 100%; + font-family: Verdana, Sans-serif, Arial, 'Trebuchet MS', 'Times New Roman'; + font-size: small; + position: absolute; + margin: 0px 0 0 0; + } + h2 + { + text-decoration: none; + font-size: 1.2em; + font-family: Verdana, Sans-serif, Arial, 'Trebuchet MS', 'Times New Roman'; + margin: 5px 0 0; + padding: 1px 5px 1px; + border: 1px solid #6b89d4; /* #84C43B; */ + -moz-border-radius: 0.3em; + background: #e6edff; /* #d7e9a7; */ + } + #watermark + { + margin: 0; + position: fixed; + top: 40%; + color: #eeeeee; + width: 100%; + height: 100%; + text-align: center; + vertical-align: middle; + font-size: 9em; + font-weight: bold; + z-index:-1; + } + --> + </xsl:comment> + </style> +</xsl:template> + +<!-- Remove the title page at all --> +<!-- +<xsl:template name="book.titlepage"> + --> + <!-- Doesn't work with Qt, grrr --> + <!--<xsl:text><div id="watermark">VirtualBox<br />Change Log</div></xsl:text>--> +<!-- +</xsl:template> +--> + +<!-- Disable any links into the manual --> +<xsl:template match="xref" name="xref"> + <xsl:text>the manual for more information</xsl:text> +</xsl:template> + +</xsl:stylesheet> diff --git a/doc/manual/docbook-html-chunks-formatcfg.xsl b/doc/manual/docbook-html-chunks-formatcfg.xsl new file mode 100644 index 00000000..b90795ad --- /dev/null +++ b/doc/manual/docbook-html-chunks-formatcfg.xsl @@ -0,0 +1,64 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> + +<!-- Chunked html file template --> +<xsl:import href="html/chunk.xsl"/> + +<xsl:import href="common-formatcfg.xsl"/> +<xsl:import href="common-html-formatcfg.xsl"/> + +<!-- Adjust some params --> +<xsl:param name="draft.mode" select="'no'"/> +<xsl:param name="suppress.navigation" select="1"></xsl:param> +<xsl:param name="header.rule" select="0"></xsl:param> +<xsl:param name="abstract.notitle.enabled" select="0"></xsl:param> +<xsl:param name="footer.rule" select="0"></xsl:param> +<xsl:param name="css.decoration" select="1"></xsl:param> +<xsl:param name="html.cleanup" select="1"></xsl:param> +<xsl:param name="css.decoration" select="1"></xsl:param> + +<xsl:param name="generate.toc"> +appendix toc,title +article/appendix nop +article toc,title +book toc,title,figure,table,example,equation +chapter toc,title +part toc,title +preface toc,title +qandadiv toc +qandaset toc +reference toc,title +sect1 nop +sect2 nop +sect3 nop +sect4 nop +sect5 nop +section nop +set toc,title +</xsl:param> + + +</xsl:stylesheet> diff --git a/doc/manual/docbook-html-one-page-formatcfg.xsl b/doc/manual/docbook-html-one-page-formatcfg.xsl new file mode 100644 index 00000000..7ffc4f75 --- /dev/null +++ b/doc/manual/docbook-html-one-page-formatcfg.xsl @@ -0,0 +1,43 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> + +<!-- Single html file template --> +<xsl:import href="html/docbook.xsl"/> + +<xsl:import href="common-formatcfg.xsl"/> +<xsl:import href="common-html-formatcfg.xsl"/> + +<!-- Adjust some params --> +<xsl:param name="draft.mode" select="'no'"/> +<xsl:param name="suppress.navigation" select="1"></xsl:param> +<xsl:param name="header.rule" select="0"></xsl:param> +<xsl:param name="abstract.notitle.enabled" select="0"></xsl:param> +<xsl:param name="footer.rule" select="0"></xsl:param> +<xsl:param name="css.decoration" select="1"></xsl:param> +<xsl:param name="html.cleanup" select="1"></xsl:param> +<xsl:param name="css.decoration" select="1"></xsl:param> + +</xsl:stylesheet> diff --git a/doc/manual/docbook-htmlhelp-formatcfg.xsl b/doc/manual/docbook-htmlhelp-formatcfg.xsl new file mode 100644 index 00000000..0786d398 --- /dev/null +++ b/doc/manual/docbook-htmlhelp-formatcfg.xsl @@ -0,0 +1,76 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> + +<xsl:import href="htmlhelp/htmlhelp.xsl"/> +<xsl:import href="common-formatcfg.xsl"/> +<xsl:import href="common-html-formatcfg.xsl"/> + +<xsl:include href="titlepage-htmlhelp.xsl"/> + +<!-- Override the style sheet stuff from common-html-formatcfg.xsl, we don't + the same as the html-chunks and html-one-page. Also, the microsoft + help viewer may have limited CSS support, depending on which browser + version it emulated, so keep it simple. --> +<xsl:template name="user.head.content"> + <style type="text/css"> + <xsl:comment> + .cmdsynopsis p + { + padding-left: 3.4em; + text-indent: -2.2em; + } + p.nextcommand + { + margin-top: 0px; + margin-bottom: 0px; + } + p.lastcommand + { + margin-top: 0px; + } + </xsl:comment> + </style> +</xsl:template> + + +<!-- for some reason, the default docbook stuff doesn't wrap simple <arg> elements + into HTML <code>, so with a default CSS a cmdsynopsis ends up with a mix of + monospace and proportional fonts. Elsewhere we hack that in the CSS, here + that turned out to be harded, so we just wrap things in <code>, risking + nested <code> elements, but who cares as long as it works... --> +<xsl:template match="group|arg"> + <xsl:choose> + <xsl:when test="name(..) = 'arg' or name(..) = 'group'"> + <xsl:apply-imports/> + </xsl:when> + <xsl:otherwise> + <code><xsl:apply-imports/></code> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + +</xsl:stylesheet> + diff --git a/doc/manual/docbook-refentry-link-replacement-xsl-gen.xsl b/doc/manual/docbook-refentry-link-replacement-xsl-gen.xsl new file mode 100644 index 00000000..8809f53f --- /dev/null +++ b/doc/manual/docbook-refentry-link-replacement-xsl-gen.xsl @@ -0,0 +1,203 @@ +<?xml version="1.0"?> +<!-- + docbook-refentry-link-replacement-xsl-gen.xsl: + XSLT stylesheet for generate a stylesheet that replaces links + to the user manual in the manpages. +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<xsl:stylesheet + version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + > + + <xsl:output method="text" version="1.0" encoding="utf-8" indent="yes"/> + <xsl:strip-space elements="*"/> + +<xsl:param name="g_sMode" select="not-specified"/> + + <!-- Translatable strings --> + <xsl:variable name="sChapter" select="'chapter'"/> + <xsl:variable name="sSection" select="'section'"/> + <xsl:variable name="sOfManual" select="'of the user manual'"/> + <xsl:variable name="sInManual" select="'in the user manual'"/> + + +<!-- Default operation is to supress output --> +<xsl:template match="node()|@*"> + <xsl:apply-templates/> +</xsl:template> + + +<!-- Remove all remarks. --> +<xsl:template match="remark"/> + +<!-- +Output header and footer. +--> +<xsl:template match="/"> + <xsl:if test="$g_sMode = 'first'"> + <xsl:text><?xml version="1.0"?> +<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" > +<xsl:output method="xml" version="1.0" encoding="utf-8" indent="yes" /> +<xsl:template match="node()|@*"> + <xsl:copy> + <xsl:apply-templates select="node()|@*"/> + </xsl:copy> +</xsl:template> + +</xsl:text> + </xsl:if> + <xsl:apply-templates/> + <xsl:if test="$g_sMode = 'last'"> + <xsl:text> +</xsl:stylesheet> +</xsl:text> + </xsl:if> +</xsl:template> + + +<!-- +Produce the transformation templates: +--> +<xsl:template match="chapter[@id]/title"> + <xsl:text> +<xsl:template match="xref[@linkend='</xsl:text> + <xsl:value-of select="../@id"/><xsl:text>']"> + <xsl:text></xsl:text><xsl:value-of select="$sChapter"/><xsl:text> </xsl:text> + <xsl:value-of select="count(../preceding-sibling::chapter) + 1"/><xsl:text> "</xsl:text> + <xsl:value-of select="normalize-space()"/> + <xsl:text>" </xsl:text><xsl:value-of select="$sInManual"/><xsl:text></xsl:text> +</xsl:template> +</xsl:text> + <xsl:apply-templates/> +</xsl:template> + +<xsl:template match="sect1[@id]/title"> + <xsl:text><xsl:template match="xref[@linkend='</xsl:text> + <xsl:value-of select="../@id"/><xsl:text>']"> + <xsl:text></xsl:text><xsl:value-of select="$sSection"/><xsl:text> </xsl:text> + <xsl:value-of select="count(../../preceding-sibling::chapter) + 1"/><xsl:text>.</xsl:text> + <xsl:value-of select="count(../preceding-sibling::sect1) + 1"/> + <xsl:text> "</xsl:text> + <xsl:value-of select="normalize-space()"/><xsl:text>" </xsl:text> + <xsl:value-of select="$sOfManual"/><xsl:text></xsl:text> +</xsl:template> +</xsl:text> + <xsl:apply-templates/> +</xsl:template> + +<xsl:template match="sect2[@id]/title"> + <xsl:text><xsl:template match="xref[@linkend='</xsl:text> + <xsl:value-of select="../@id"/><xsl:text>']"> + <xsl:text></xsl:text><xsl:value-of select="$sSection"/><xsl:text> </xsl:text> + <xsl:value-of select="count(../../../preceding-sibling::chapter) + 1"/><xsl:text>.</xsl:text> + <xsl:value-of select="count(../../preceding-sibling::sect1) + 1"/><xsl:text>.</xsl:text> + <xsl:value-of select="count(../preceding-sibling::sect2) + 1"/> + <xsl:text> "</xsl:text> + <xsl:value-of select="normalize-space()"/><xsl:text>" </xsl:text> + <xsl:value-of select="$sOfManual"/><xsl:text></xsl:text> +</xsl:template> +</xsl:text> + <xsl:apply-templates/> +</xsl:template> + +<xsl:template match="sect3[@id]/title"> + <xsl:text><xsl:template match="xref[@linkend='</xsl:text> + <xsl:value-of select="../@id"/><xsl:text>']"> + <xsl:text></xsl:text><xsl:value-of select="$sSection"/><xsl:text> </xsl:text> + <xsl:value-of select="count(../../../../preceding-sibling::chapter) + 1"/><xsl:text>.</xsl:text> + <xsl:value-of select="count(../../../preceding-sibling::sect1) + 1"/><xsl:text>.</xsl:text> + <xsl:value-of select="count(../../preceding-sibling::sect2) + 1"/><xsl:text>.</xsl:text> + <xsl:value-of select="count(../preceding-sibling::sect3) + 1"/> + <xsl:text> "</xsl:text> + <xsl:value-of select="normalize-space()"/><xsl:text>" </xsl:text> + <xsl:value-of select="$sOfManual"/><xsl:text></xsl:text> +</xsl:template> +</xsl:text> + <xsl:apply-templates/> +</xsl:template> + +<xsl:template match="preface[@id]/title"> + <xsl:text><xsl:template match="xref[@linkend='</xsl:text> + <xsl:value-of select="../@id"/><xsl:text>']"> + <xsl:text>"</xsl:text> + <xsl:value-of select="normalize-space()"/><xsl:text>" </xsl:text> + <xsl:value-of select="$sOfManual"/><xsl:text></xsl:text> +</xsl:template> +</xsl:text> + <xsl:apply-templates/> +</xsl:template> + +<xsl:template match="refentry[@id]/refentryinfo/title"> + <xsl:text><xsl:template match="xref[@linkend='</xsl:text> + <xsl:value-of select="../../@id"/><xsl:text>']"> + <xsl:text> "</xsl:text> + <xsl:value-of select="normalize-space()"/><xsl:text>"</xsl:text> +</xsl:template> +</xsl:text> + <xsl:apply-templates/> +</xsl:template> + +<xsl:template match="refsect2[@id]/title"> + <xsl:text><xsl:template match="xref[@linkend='</xsl:text> + <xsl:value-of select="../@id"/><xsl:text>']"> + <xsl:text>"</xsl:text> + <xsl:value-of select="normalize-space()"/><xsl:text>"</xsl:text> +</xsl:template> +</xsl:text> + <xsl:apply-templates/> +</xsl:template> + + +<!-- + Debug/Diagnostics: Return the path to the specified node (by default the current). + --> +<xsl:template name="get-node-path"> + <xsl:param name="Node" select="."/> + <xsl:for-each select="$Node"> + <xsl:for-each select="ancestor-or-self::node()"> + <xsl:choose> + <xsl:when test="name(.) = ''"> + <xsl:text>text()</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="concat('/', name(.))"/> + <xsl:choose> + <xsl:when test="@id"> + <xsl:text>[@id=</xsl:text> + <xsl:value-of select="@id"/> + <xsl:text>]</xsl:text> + </xsl:when> + <xsl:when test="position() > 1"> + <xsl:text>[</xsl:text><xsl:value-of select="position()"/><xsl:text>]</xsl:text> + </xsl:when> + </xsl:choose> + </xsl:otherwise> + </xsl:choose> + </xsl:for-each> + </xsl:for-each> +</xsl:template> + +</xsl:stylesheet> + diff --git a/doc/manual/docbook-refentry-to-C-help.xsl b/doc/manual/docbook-refentry-to-C-help.xsl new file mode 100644 index 00000000..393fa5e7 --- /dev/null +++ b/doc/manual/docbook-refentry-to-C-help.xsl @@ -0,0 +1,999 @@ +<?xml version="1.0"?> +<!-- + docbook-refentry-to-manual-sect1.xsl: + XSLT stylesheet for nicking the refsynopsisdiv bit of a + refentry (manpage) for use in the command overview section + in the user manual. +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<xsl:stylesheet + version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:str="http://xsltsl.org/string" + > + + <xsl:import href="string.xsl"/> + <xsl:import href="common-formatcfg.xsl"/> + + <xsl:output method="text" version="1.0" encoding="utf-8" indent="yes"/> + <xsl:strip-space elements="*"/> + + <xsl:param name="g_fDebugText" select="0"/> + + <xsl:variable name="g_sUnderlineRefSect1"> + <xsl:text>===================================================================================================================</xsl:text> + </xsl:variable> + <xsl:variable name="g_sUnderlineRefSect2"> + <xsl:text>-------------------------------------------------------------------------------------------------------------------</xsl:text> + </xsl:variable> + <xsl:variable name="g_sNewLine"><xsl:value-of select="' '" /></xsl:variable> + + <!-- Sub-command style command (true) or single command (false). --> + <xsl:variable name="g_fSubCommands" select="not(not(//refsect2[@id]))" /> + + <!-- Translatable strings --> + <xsl:variable name="sUsage" select="'Usage'"/> + <xsl:variable name="sUsageUnderscore" select="'====='"/> + + + <!-- Default action, do nothing. --> + <xsl:template match="node()|@*"/> + + <!-- + main() - because we need to order the output in a specific manner + that is contrary to the data flow in the refentry, this is + going to look a bit more like a C program than a stylesheet. + --> + <xsl:template match="refentry"> + <!-- Assert refetry expectations. --> + <xsl:if test="not(./refsynopsisdiv)"> + <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>refentry must have a refsynopsisdiv</xsl:message> + </xsl:if> + <xsl:if test="not(./refentryinfo/title)"> + <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>refentry must have a refentryinfo with title</xsl:message> + </xsl:if> + <xsl:if test="not(./refmeta/refentrytitle)"> + <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>refentry must have a refentryinfo with title</xsl:message> + </xsl:if> + <xsl:if test="./refmeta/refentrytitle != ./refnamediv/refname"> + <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>The refmeta/refentrytitle and the refnamediv/refname must be identical</xsl:message> + </xsl:if> + <xsl:if test="not(./refsect1/title)"> + <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>refentry must have a refsect1 with title</xsl:message> + </xsl:if> + <xsl:if test="not(@id) or @id = ''"> + <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>refentry must have an id attribute</xsl:message> + </xsl:if> + + <!-- variables --> + <xsl:variable name="sBaseId" select="@id"/> + <xsl:variable name="sDataBaseSym" select="concat('g_', translate(@id, '-', '_'))"/> + + + <!-- + Convert the refsynopsisdiv into REFENTRY::Synopsis data. + --> + <xsl:text> + +static const RTMSGREFENTRYSTR </xsl:text><xsl:value-of select="$sDataBaseSym"/><xsl:text>_synopsis[] = +{</xsl:text> + <xsl:for-each select="./refsynopsisdiv/cmdsynopsis"> + <!-- Assert synopsis expectations --> + <xsl:if test="not(@id) or substring-before(@id, '-') != 'synopsis'"> + <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>The refsynopsisdiv/cmdsynopsis elements must have an id starting with 'synopsis-'.</xsl:message> + </xsl:if> + <xsl:if test="not(starts-with(substring-after(@id, '-'), $sBaseId))"> + <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>The refsynopsisdiv/cmdsynopsis elements @id is expected to include the refentry @id.</xsl:message> + </xsl:if> + <xsl:if test="not(../../refsect1/refsect2[@id=./@id]) and $g_fSubCommands"> + <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>No refsect2 with id="<xsl:value-of select="@id"/>" found.</xsl:message> + </xsl:if> + + <!-- Do the work. --> + <xsl:apply-templates select="."/> + + </xsl:for-each> + <xsl:text> +};</xsl:text> + + + <!-- + Convert the whole manpage to help text. + --> + <xsl:text> +static const RTMSGREFENTRYSTR </xsl:text><xsl:value-of select="$sDataBaseSym"/><xsl:text>_full_help[] = +{</xsl:text> + <!-- We start by combining the refentry title and the refpurpose into a short description. --> + <xsl:text> + { </xsl:text><xsl:call-template name="calc-scope-for-refentry"/><xsl:text>, + "</xsl:text> + <xsl:apply-templates select="./refentryinfo/title/node()"/> + <xsl:text> -- </xsl:text> + <xsl:call-template name="capitalize"> + <xsl:with-param name="text"> + <xsl:apply-templates select="./refnamediv/refpurpose/node()"/> + </xsl:with-param> + </xsl:call-template> + <xsl:text>." }, + { RTMSGREFENTRYSTR_SCOPE_SAME, "" },</xsl:text> + + <!-- The follows the usage (synopsis) section. --> + <xsl:text> + { RTMSGREFENTRYSTR_SCOPE_GLOBAL, + "</xsl:text><xsl:value-of select="$sUsage"/><xsl:text>" }, + { RTMSGREFENTRYSTR_SCOPE_SAME, + "</xsl:text><xsl:value-of select="$sUsageUnderscore"/><xsl:text>" },</xsl:text> + <xsl:apply-templates select="./refsynopsisdiv/node()"/> + + <!-- Then comes the description and other refsect1 --> + <xsl:for-each select="./refsect1"> + <xsl:if test="name(*[1]) != 'title'"><xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Expected title as the first element in refsect1.</xsl:message></xsl:if> + <xsl:if test="text()"><xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>No text supported in refsect1.</xsl:message></xsl:if> + <xsl:if test="not(./remark[@role='help-skip'])"> + <xsl:variable name="sTitle"> + <xsl:apply-templates select="./title/node()"/> + </xsl:variable> + <xsl:text> + { </xsl:text><xsl:call-template name="calc-scope-refsect1"/><xsl:text>, "" }, + { RTMSGREFENTRYSTR_SCOPE_SAME, + "</xsl:text><xsl:value-of select="$sTitle"/><xsl:text>" }, + { RTMSGREFENTRYSTR_SCOPE_SAME, + "</xsl:text> + <xsl:value-of select="substring($g_sUnderlineRefSect1, 1, string-length($sTitle))"/> + <xsl:text>" },</xsl:text> + + <xsl:apply-templates select="./*[name() != 'title']"/> + + <xsl:text> + { RTMSGREFENTRYSTR_SCOPE_SAME, "" },</xsl:text> + </xsl:if> + </xsl:for-each> + + <xsl:text> +};</xsl:text> + + <!-- + Generate the refentry structure. + --> + <xsl:text> +static const RTMSGREFENTRY </xsl:text><xsl:value-of select="$sDataBaseSym"/><xsl:text> = +{ + /* .idInternal = */ HELP_CMD_</xsl:text> + <xsl:choose> + <xsl:when test="contains(@id, '-')"> + <xsl:call-template name="str:to-upper"> <!-- Multi level command. --> + <xsl:with-param name="text" select="translate(substring-after(@id, '-'), '-', '_')"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name="str:to-upper"> <!-- Simple command. --> + <xsl:with-param name="text" select="@id"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> + <xsl:text>, + /* .Synopsis = */ { RT_ELEMENTS(</xsl:text> + <xsl:value-of select="$sDataBaseSym"/><xsl:text>_synopsis), 0, </xsl:text> + <xsl:value-of select="$sDataBaseSym"/><xsl:text>_synopsis }, + /* .Help = */ { RT_ELEMENTS(</xsl:text> + <xsl:value-of select="$sDataBaseSym"/><xsl:text>_full_help), 0, </xsl:text> + <xsl:value-of select="$sDataBaseSym"/><xsl:text>_full_help }, + /* pszBrief = */ "</xsl:text> + <xsl:apply-templates select="./refnamediv/refpurpose/node()"/> + <!-- TODO: Add the command name too. --> + <xsl:text>" +}; +</xsl:text> + </xsl:template> + + + <!-- + Convert command synopsis to text. + --> + <xsl:template match="cmdsynopsis"> + <xsl:if test="text()"><xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>cmdsynopsis with text is not supported.</xsl:message></xsl:if> + <xsl:if test="position() = 1"> + <xsl:text> + { </xsl:text><xsl:call-template name="calc-scope-cmdsynopsis"/><xsl:text> | RTMSGREFENTRYSTR_FLAGS_SYNOPSIS, "" },</xsl:text> + </xsl:if> + <xsl:text> + { </xsl:text><xsl:call-template name="calc-scope-cmdsynopsis"/><xsl:text> | RTMSGREFENTRYSTR_FLAGS_SYNOPSIS, + "</xsl:text><xsl:call-template name="emit-indentation"/><xsl:apply-templates select="*|@*"/><xsl:text>" },</xsl:text> + </xsl:template> + + <xsl:template match="sbr"> + <xsl:text>" }, + { RTMSGREFENTRYSTR_SCOPE_SAME | RTMSGREFENTRYSTR_FLAGS_SYNOPSIS, + " </xsl:text><xsl:call-template name="emit-indentation"/> <!-- hardcoded in VBoxManageHelp.cpp too --> + </xsl:template> + + <xsl:template match="cmdsynopsis/command"> + <xsl:text>" }, + { RTMSGREFENTRYSTR_SCOPE_SAME | RTMSGREFENTRYSTR_FLAGS_SYNOPSIS, + "</xsl:text><xsl:call-template name="emit-indentation"/> + <xsl:apply-templates select="node()|@*"/> + </xsl:template> + + <xsl:template match="cmdsynopsis/command[1]" priority="2"> + <xsl:apply-templates select="node()|@*"/> + </xsl:template> + + <xsl:template match="command|option|computeroutput|literal|emphasis|filename|citetitle|note"> + <xsl:apply-templates select="node()|@*"/> + </xsl:template> + + <xsl:template match="ulink"> + <xsl:value-of select="@url"/> + </xsl:template> + + <xsl:template match="replaceable"> + <xsl:choose> + <xsl:when test="ancestor::arg"> + <xsl:apply-templates /> + </xsl:when> + <xsl:otherwise> + <xsl:text><</xsl:text> + <xsl:apply-templates /> + <xsl:text>></xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <!-- duplicated in docbook2latex.xsl --> + <xsl:template match="arg|group"> + <!-- separator char if we're not the first child --> + <xsl:if test="position() > 1"> + <xsl:choose> + <xsl:when test="parent::group"><xsl:value-of select="$arg.or.sep"/></xsl:when> + <xsl:when test="ancestor-or-self::*/@sepchar"><xsl:value-of select="ancestor-or-self::*/@sepchar"/></xsl:when> + <xsl:otherwise><xsl:text> </xsl:text></xsl:otherwise> + </xsl:choose> + </xsl:if> + + <!-- open wrapping --> + <xsl:variable name="fWrappers" select="not(ancestor::group)"/> + <xsl:if test="$fWrappers"> + <xsl:choose> + <xsl:when test="not(@choice) or @choice = ''"> <xsl:value-of select="$arg.choice.def.open.str"/></xsl:when> + <xsl:when test="@choice = 'opt'"> <xsl:value-of select="$arg.choice.opt.open.str"/></xsl:when> + <xsl:when test="@choice = 'req'"> <xsl:value-of select="$arg.choice.req.open.str"/></xsl:when> + <xsl:when test="@choice = 'plain'"/> + <xsl:otherwise><xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Invalid arg choice: "<xsl:value-of select="@choice"/>"</xsl:message></xsl:otherwise> + </xsl:choose> + </xsl:if> + + <!-- render the arg (TODO: may need to do more work here) --> + <xsl:apply-templates /> + + <!-- repeat wrapping --> + <xsl:choose> + <xsl:when test="@rep = 'norepeat' or not(@rep) or @rep = ''"/> + <xsl:when test="@rep = 'repeat'"> <xsl:value-of select="$arg.rep.repeat.str"/></xsl:when> + <xsl:otherwise><xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Invalid rep choice: "<xsl:value-of select="@rep"/>"</xsl:message></xsl:otherwise> + </xsl:choose> + + <!-- close wrapping --> + <xsl:if test="$fWrappers"> + <xsl:choose> + <xsl:when test="not(@choice) or @choice = ''"> <xsl:value-of select="$arg.choice.def.close.str"/></xsl:when> + <xsl:when test="@choice = 'opt'"> <xsl:value-of select="$arg.choice.opt.close.str"/></xsl:when> + <xsl:when test="@choice = 'req'"> <xsl:value-of select="$arg.choice.req.close.str"/></xsl:when> + </xsl:choose> + <!-- Add a space padding if we're the last element in a repeating arg or group --> + <xsl:if test="(parent::arg or parent::group) and not(following-sibiling)"> + <xsl:text> </xsl:text> + </xsl:if> + </xsl:if> + </xsl:template> + + + <!-- + refsect2 + --> + <xsl:template match="refsect2"> + <!-- assertions --> + <xsl:if test="text()"><xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>refsect2 shouldn't contain text</xsl:message></xsl:if> + <xsl:if test="count(./title) != 1"><xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>refsect2 requires a title (<xsl:value-of select="ancestor-or-self::*[@id][1]/@id"/>)</xsl:message></xsl:if> + + <!-- title / command synopsis - sets the scope. --> + <xsl:variable name="sTitle"> + <xsl:apply-templates select="./title/text()"/> + </xsl:variable> + <xsl:text> + { </xsl:text><xsl:call-template name="calc-scope-refsect2"/><xsl:text>, "" }, + { RTMSGREFENTRYSTR_SCOPE_SAME, + "</xsl:text><xsl:call-template name="emit-indentation"/> + <xsl:value-of select="$sTitle"/> + <xsl:text>" }, + { RTMSGREFENTRYSTR_SCOPE_SAME, + "</xsl:text><xsl:call-template name="emit-indentation"/> + <xsl:value-of select="substring($g_sUnderlineRefSect2, 1, string-length($sTitle))"/> + <xsl:text>" },</xsl:text> + +<!-- <xsl:if test="./*[name() != 'title']/following:: + { RTMSGREFENTRYSTR_SCOPE_SAME, "y" },</xsl:text> cmdsynopsis --> + + <!-- Format the text in the section --> + <xsl:for-each select="./*[name() != 'title']"> + <xsl:apply-templates select="."/> + </xsl:for-each> + + <!-- Add two blank lines, unless we're the last element in this refsect1. --> + <xsl:if test="position() != last()"> + <xsl:text> + { RTMSGREFENTRYSTR_SCOPE_SAME, "" },</xsl:text> + </xsl:if> + </xsl:template> + + + <!-- + para + --> + <xsl:template match="para"> + <xsl:if test="position() != 1 or not(parent::listitem)"> + <xsl:text> + { RTMSGREFENTRYSTR_SCOPE_SAME, "" },</xsl:text> + </xsl:if> + <xsl:call-template name="process-mixed"/> + </xsl:template> + + + <!-- + variablelist + --> + <xsl:template match="variablelist"> + <xsl:if test="*[not(self::varlistentry)]|text()"> + <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Only varlistentry elements are supported in variablelist </xsl:message> + </xsl:if> + <xsl:for-each select="./varlistentry"> + <xsl:if test="not(term) or not(listitem) or count(listitem) > 1"> + <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Expected one or more term members and exactly one listentry member in varlistentry element.</xsl:message> + </xsl:if> + <xsl:if test="(not(@spacing) or @spacing != 'compact') and (position() > 1 or (count(../preceding-sibling::*) - count(../preceding-sibling::title) > 0))"> + <xsl:text> + { RTMSGREFENTRYSTR_SCOPE_SAME, "" },</xsl:text> + </xsl:if> + <xsl:apply-templates select="*"/> + </xsl:for-each> + </xsl:template> + + <xsl:template match="varlistentry/term"> + <xsl:call-template name="process-mixed"/> + </xsl:template> + + <xsl:template match="varlistentry/listitem"> + <xsl:call-template name="check-children"> + <xsl:with-param name="UnsupportedNodes" select="*[not(self::para or self::itemizedlist or self::orderedlist or self::variablelist or self::note)]|text()"/> + <xsl:with-param name="SupportedNames">para, itemizedlist, orderedlist and note</xsl:with-param> + </xsl:call-template> + + <xsl:apply-templates select="*"/> + </xsl:template> + + + <!-- + itemizedlist and orderedlist + --> + <xsl:template match="itemizedlist|orderedlist"> + <xsl:if test="*[not(self::listitem)]|text()"> + <xsl:message terminate="yes"> + <xsl:call-template name="error-prefix"/>Only listitem elements are supported in <xsl:value-of select="name()"/>: + <xsl:call-template name="list-nodes"> + <xsl:with-param name="Nodes" select="*[not(self::listitem)]|text()"/> + </xsl:call-template> + </xsl:message> + </xsl:if> + <xsl:if test="parent::para"> + <xsl:message terminate="yes"><xsl:value-of select="name()"/> inside a para is current not supported. <!-- no newline + -->Close the para before the list, it makes no difference to html and latex/pdf output.</xsl:message> + </xsl:if> + <xsl:if test="position() != 1 and (not(@spacing) or @spacing != 'compact')"> + <xsl:text> + { RTMSGREFENTRYSTR_SCOPE_SAME, "" },</xsl:text> + </xsl:if> + <xsl:for-each select="./listitem"> + <xsl:apply-templates select="*"/> + </xsl:for-each> + </xsl:template> + + <xsl:template match="itemizedlist/listitem|orderedlist/listitem"> + <xsl:if test="*[not(self::para)]|text()"> + <xsl:message terminate="yes"> + <xsl:call-template name="error-prefix"/>Expected <xsl:value-of select="name()"/>/listitem to only contain para elements: + <xsl:call-template name="list-nodes"> + <xsl:with-param name="Nodes" select="*[not(self::para)]|text()"/> + </xsl:call-template> + </xsl:message> + </xsl:if> + + <xsl:if test="position() != 1 and @spaceing != 'compact'"> + <xsl:text> + { RTMSGREFENTRYSTR_SCOPE_SAME, "" },</xsl:text> + </xsl:if> + <xsl:apply-templates select="*"/> + </xsl:template> + + + <!-- + Screen + --> + <xsl:template match="screen"> + <xsl:if test="ancestor::para"> + <xsl:text>" },</xsl:text> + </xsl:if> + + <xsl:text> + { RTMSGREFENTRYSTR_SCOPE_SAME, + "</xsl:text> + + <xsl:for-each select="node()"> + <xsl:choose> + <xsl:when test="name() = ''"> + <xsl:call-template name="screen_text_line"> + <xsl:with-param name="sText" select="."/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:if test="*"> + <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Support for elements under screen has not been implemented: <xsl:value-of select="name()"/></xsl:message> + </xsl:if> + </xsl:otherwise> + </xsl:choose> + </xsl:for-each> + + <xsl:if test="not(ancestor::para)"> + <xsl:text>" },</xsl:text> + </xsl:if> + </xsl:template> + + <xsl:template name="screen_text_line"> + <xsl:param name="sText"/> + + <xsl:choose> + <xsl:when test="contains($sText, '
')"> + <xsl:call-template name="escape_fixed_text"> + <xsl:with-param name="sText" select="substring-before($sText,'
')"/> + </xsl:call-template> + + <xsl:if test="substring-after($sText,'
')"> + <xsl:text>" }, + { RTMSGREFENTRYSTR_SCOPE_SAME, + "</xsl:text> + <xsl:call-template name="screen_text_line"> + <xsl:with-param name="sText" select="substring-after($sText,'
')"/> + </xsl:call-template> + </xsl:if> + </xsl:when> + + <xsl:otherwise> <!-- no newline, so use the whole string --> + <xsl:call-template name="escape_fixed_text"> + <xsl:with-param name="sText" select="$sText"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <!-- Normalizes the current text node taking tailing and leading spaces + into account (unlike normalize-space which strips them mercilessly). --> + <xsl:template name="my-normalize-space-current"> + <!-- <xsl:message>dbg0: position=<xsl:value-of select="position()"/> last=<xsl:value-of select="last()"/> .=|<xsl:value-of select="."/>|</xsl:message> --> + <xsl:if test="(starts-with(.,' ') or starts-with(., $g_sNewLine)) and position() != 1"> + <xsl:value-of select="' '"/> + </xsl:if> + <xsl:value-of select="normalize-space(.)"/> + <xsl:if test="((substring(.,string-length(.)) = ' ') or (substring(.,string-length(.)) = $g_sNewLine)) and position() != last()"> + <xsl:value-of select="' '"/> + </xsl:if> + </xsl:template> + + <!-- + Text escaping for C. + --> + <xsl:template match="text()" name="escape_text"> + <!-- Leading whitespace hack! --> + <xsl:if test="(starts-with(.,' ') or starts-with(.,$g_sNewLine)) and position() != 1"> + <xsl:text> </xsl:text> + <xsl:if test="boolean($g_fDebugText)"> + <xsl:message>text: add lead space</xsl:message> + </xsl:if> + </xsl:if> + + <!-- Body of text --> + <xsl:choose> + + <xsl:when test="contains(., '\') or contains(., '"')"> + <xsl:variable name="sTmp"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="normalize-space(.)"/> + <xsl:with-param name="replace" select="'\'"/> + <xsl:with-param name="with" select="'\\'"/> + <xsl:with-param name="disable-output-escaping" select="yes"/> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="sTmp2"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$sTmp"/> + <xsl:with-param name="replace" select="'"'"/> + <xsl:with-param name="with" select="'\"'"/> + <xsl:with-param name="disable-output-escaping" select="yes"/> + </xsl:call-template> + </xsl:variable> + <xsl:value-of select="$sTmp2"/> + <xsl:if test="boolean($g_fDebugText)"> + <xsl:message>text: |<xsl:value-of select="$sTmp2"/>|(1)</xsl:message> + </xsl:if> + </xsl:when> + + <xsl:otherwise> + <xsl:value-of select="normalize-space(.)"/> + <xsl:if test="boolean($g_fDebugText)"> + <xsl:message>text: |<xsl:value-of select="normalize-space(.)"/>|(2)</xsl:message> + </xsl:if> + </xsl:otherwise> + </xsl:choose> + + <!-- Trailing whitespace hack! --> + <xsl:if test="(substring(.,string-length(.)) = ' ' or substring(.,string-length(.)) = $g_sNewLine) and position() != last() and string-length(.) != 1"> + <xsl:text> </xsl:text> + <xsl:if test="boolean($g_fDebugText)"> + <xsl:message>text: add tail space</xsl:message> + </xsl:if> + </xsl:if> + + </xsl:template> + + <!-- Elements producing non-breaking strings (single line). --> + <xsl:template match="command/text()|option/text()|computeroutput/text()|arg/text()|filename/text()" name="escape_fixed_text"> + <xsl:param name="sText"><xsl:call-template name="my-normalize-space-current"/></xsl:param> + <xsl:choose> + + <xsl:when test="contains($sText, '\') or contains($sText, '"')"> + <xsl:variable name="sTmp1"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$sText"/> + <xsl:with-param name="replace" select="'\'"/> + <xsl:with-param name="with" select="'\\'"/> + <xsl:with-param name="disable-output-escaping" select="yes"/> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="sTmp2"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$sTmp1"/> + <xsl:with-param name="replace" select="'"'"/> + <xsl:with-param name="with" select="'\"'"/> + <xsl:with-param name="disable-output-escaping" select="yes"/> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="sTmp3"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$sTmp2"/> + <xsl:with-param name="replace" select="' '"/> + <xsl:with-param name="with" select="'\b'"/> + <xsl:with-param name="disable-output-escaping" select="yes"/> + </xsl:call-template> + </xsl:variable> + <xsl:value-of select="$sTmp3"/> + <xsl:if test="boolean($g_fDebugText)"> + <xsl:message>text! |<xsl:value-of select="$sTmp3"/>|</xsl:message> + </xsl:if> + </xsl:when> + + <xsl:when test="contains($sText, ' ')"> + <xsl:variable name="sTmp"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$sText"/> + <xsl:with-param name="replace" select="' '"/> + <xsl:with-param name="with" select="'\b'"/> + <xsl:with-param name="disable-output-escaping" select="yes"/> + </xsl:call-template> + </xsl:variable> + <xsl:value-of select="$sTmp"/> + <xsl:if test="boolean($g_fDebugText)"> + <xsl:message>text! |<xsl:value-of select="$sTmp"/>|</xsl:message> + </xsl:if> + </xsl:when> + + <xsl:otherwise> + <xsl:value-of select="$sText"/> + <xsl:if test="boolean($g_fDebugText)"> + <xsl:message>text! |<xsl:value-of select="$sText"/>|</xsl:message> + </xsl:if> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + + <!-- + Unsupported elements and elements handled directly. + --> + <xsl:template match="synopfragment|synopfragmentref|title|refsect1"> + <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>The <xsl:value-of select="name()"/> element is not supported</xsl:message> + </xsl:template> + + <xsl:template match="xref"> + <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>The <xsl:value-of select="name()"/> element is not supported, most likely the linkend is not defined or incorrectly processed by docbook-refentry-link-replacement-xsl-gen.xsl</xsl:message> + </xsl:template> + + <!-- + Fail on misplaced scoping remarks. + --> + <xsl:template match="remark[@role = 'help-scope']"> + <xsl:choose> + <xsl:when test="parent::refsect1"/> + <xsl:when test="parent::refsect2"/> + <xsl:when test="parent::cmdsynopsis and ancestor::refsynopsisdiv"/> + <xsl:otherwise> + <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Misplaced remark/@role=help-scope element. +Only supported on: refsect1, refsect2, refsynopsisdiv/cmdsynopsis</xsl:message> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <!-- + Execute synopsis copy remark (avoids duplication for complicated xml). + --> + <xsl:template match="remark[@role = 'help-copy-synopsis']"> + <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>remark/@role=help-copy-synopsis is not supported by this stylesheet. Must preprocess input!</xsl:message> + </xsl:template> + + <!-- + Warn about unhandled elements + --> + <xsl:template match="*"> + <xsl:message terminate="no">Warning: Unhandled element: <!-- no newline --> + <xsl:for-each select="ancestor-or-self::*"> + <xsl:text>/</xsl:text> + <xsl:value-of select="name(.)"/> + <xsl:if test="@id"> + <xsl:value-of select="concat('[id=', @id ,']')"/> + </xsl:if> + </xsl:for-each> + </xsl:message> + </xsl:template> + + + <!-- + Functions + Functions + Functions + --> + + <!-- + Processes mixed children, i.e. both text and regular elements. + Normalizes whitespace. --> + <xsl:template name="process-mixed"> + <xsl:text> + { RTMSGREFENTRYSTR_SCOPE_SAME, + "</xsl:text><xsl:call-template name="emit-indentation"/> + + <xsl:for-each select="node()[not(self::remark)]"> + <xsl:choose> + <xsl:when test="name() = ''"> + <xsl:call-template name="escape_text"/> + </xsl:when> + <xsl:otherwise> + <xsl:apply-templates select="."/> + </xsl:otherwise> + </xsl:choose> + </xsl:for-each> + + <xsl:text>" },</xsl:text> + </xsl:template> + + + <!-- + Element specific scoping. + --> + + <xsl:template name="calc-scope-for-refentry"> + <xsl:text>HELP_SCOPE_</xsl:text> + <xsl:choose> + <xsl:when test="contains(@id, '-')"> <!-- Multi level command. --> + <xsl:call-template name="str:to-upper"> + <xsl:with-param name="text" select="translate(substring-after(@id, '-'), '-', '_')"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> <!-- Single command. --> + <xsl:call-template name="str:to-upper"> + <xsl:with-param name="text" select="@id"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <!-- Figures out the scope of a refsect1 element. --> + <xsl:template name="calc-scope-refsect1"> + <xsl:choose> + <xsl:when test="title[text() = 'Description']"> + <xsl:text>RTMSGREFENTRYSTR_SCOPE_GLOBAL</xsl:text> + </xsl:when> + <xsl:when test="@id or remark[@role='help-scope']"> + <xsl:call-template name="calc-scope-from-remark-or-id"/> + </xsl:when> + <xsl:otherwise> + <xsl:text>RTMSGREFENTRYSTR_SCOPE_GLOBAL</xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <!-- Figures out the scope of a refsect2 element. --> + <xsl:template name="calc-scope-refsect2"> + <xsl:choose> + <xsl:when test="@id or remark[@role='help-scope']"> + <xsl:call-template name="calc-scope-from-remark-or-id"/> + </xsl:when> + <xsl:otherwise> + <xsl:text>RTMSGREFENTRYSTR_SCOPE_SAME</xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <!-- Figures out the scope of a refsect1 element. --> + <xsl:template name="calc-scope-cmdsynopsis"> + <xsl:choose> + <xsl:when test="ancestor::refsynopsisdiv"> + <xsl:call-template name="calc-scope-from-remark-or-id"> + <xsl:with-param name="sId" select="substring-after(@id, '-')"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:text>RTMSGREFENTRYSTR_SCOPE_SAME</xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + + <!-- + Scoping worker functions. + --> + + <!-- Calculates the current scope from the scope remark or @id. --> + <xsl:template name="calc-scope-from-remark-or-id"> + <xsl:param name="sId" select="@id"/> + <xsl:choose> + <xsl:when test="remark[@role='help-scope']"> + <xsl:call-template name="calc-scope-consts-from-remark"/> + </xsl:when> + <xsl:when test="$sId != ''"> + <xsl:call-template name="calc-scope-const-from-id"> + <xsl:with-param name="sId" select="$sId"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>expected remark child or id attribute.</xsl:message> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <!-- Turns a @id into a scope constant. + Some woodoo taking place here here that chops the everything up to and + including the first refentry/@id word from all IDs before turning them into + constants (word delimiter '-'). --> + <xsl:template name="calc-scope-const-from-id"> + <xsl:param name="sId" select="@id"/> + <xsl:param name="sAncestorId" select="ancestor::refentry/@id"/> + <xsl:text>HELP_SCOPE_</xsl:text> + <xsl:choose> + <xsl:when test="not($sAncestorId)"> <!-- Sanity check. --> + <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>calc-scope-const-from-id is invoked without an refentry ancestor with a id. <xsl:call-template name="get-node-path"/> </xsl:message> + </xsl:when> + + <xsl:when test="contains($sAncestorId, '-')"> <!-- Multi level command. --> + <xsl:variable name="sPrefix" select="concat(substring-before($sAncestorId, '-'), '-')"/> + <xsl:if test="not(contains($sId, $sPrefix))"> + <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Expected sId (<xsl:value-of select="$sId"/>) to contain <xsl:value-of select="$sPrefix"/></xsl:message> + </xsl:if> + <xsl:call-template name="str:to-upper"> + <xsl:with-param name="text" select="translate(substring-after($sId, $sPrefix), '-', '_')"/> + </xsl:call-template> + </xsl:when> + + <xsl:otherwise> <!-- Single command. --> + <xsl:call-template name="str:to-upper"> + <xsl:with-param name="text" select="translate($sId, '-', '_')"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <!-- Turns a remark into one or more scope constants. --> + <xsl:template name="calc-scope-consts-from-remark"> + <xsl:param name="sCondition" select="remark/@condition"/> + <xsl:variable name="sNormalized" select="concat(normalize-space(translate($sCondition, ',;:|', ' ')), ' ')"/> + <xsl:if test="$sNormalized = ' ' or $sNormalized = ''"> + <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Empty @condition for help-scope remark.</xsl:message> + </xsl:if> + <xsl:choose> + <xsl:when test="substring-before($sNormalized, ' ') = 'GLOBAL'"> + <xsl:text>RTMSGREFENTRYSTR_SCOPE_GLOBAL</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>HELP_SCOPE_</xsl:text><xsl:value-of select="substring-before($sNormalized, ' ')"/> + </xsl:otherwise> + </xsl:choose> + <xsl:call-template name="calc-scope-const-from-remark-worker"> + <xsl:with-param name="sList" select="substring-after($sNormalized, ' ')"/> + </xsl:call-template> + </xsl:template> + + <xsl:template name="calc-scope-const-from-remark-worker"> + <xsl:param name="sList"/> + <xsl:if test="$sList != ''"> + <xsl:choose> + <xsl:when test="substring-before($sList, ' ') = 'GLOBAL'"> + <xsl:text>| RTMSGREFENTRYSTR_SCOPE_GLOBAL</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text> | HELP_SCOPE_</xsl:text><xsl:value-of select="substring-before($sList, ' ')"/> + </xsl:otherwise> + </xsl:choose> + <xsl:call-template name="calc-scope-const-from-remark-worker"> + <xsl:with-param name="sList" select="substring-after($sList, ' ')"/> + </xsl:call-template> + </xsl:if> + </xsl:template> + + + <!-- + Calculates and emits indentation list markup. + --> + <xsl:template name="emit-indentation"> + <xsl:variable name="iDepth" select="count(ancestor-or-self::*)"/> + <xsl:for-each select="ancestor-or-self::*"> + <xsl:choose> + + <xsl:when test="self::refsect1 + | self::refsect2 + | self::refsect3 + | self::refsynopsisdiv"> + <xsl:text> </xsl:text> + </xsl:when> + + <xsl:when test="self::term"> + <!-- currently no indent. --> + </xsl:when> + + <!-- Evidence here (especially with orderedlist) that doing list by for-each + listitem in the template matching the list type would be easier... --> + <xsl:when test="self::listitem and parent::itemizedlist and (position() + 1) = $iDepth"> + <xsl:text> - </xsl:text> + </xsl:when> + + <xsl:when test="self::listitem and parent::orderedlist and (position() + 1) = $iDepth"> + <xsl:variable name="iNumber" select="count(preceding-sibling::listitem) + 1"/> + <xsl:if test="$iNumber <= 9"> + <xsl:text> </xsl:text> + </xsl:if> + <xsl:value-of select="$iNumber"/> + <xsl:text>. </xsl:text> + </xsl:when> + + <xsl:when test="self::listitem"> + <xsl:text> </xsl:text> + </xsl:when> + + </xsl:choose> + </xsl:for-each> + </xsl:template> + + <!-- + Captializes the given text. + --> + <xsl:template name="capitalize"> + <xsl:param name="text"/> + <xsl:call-template name="str:to-upper"> + <xsl:with-param name="text" select="substring($text,1,1)"/> + </xsl:call-template> + <xsl:value-of select="substring($text,2)"/> + </xsl:template> + + + <!-- + Debug/Diagnostics: Return the path to the specified node (by default the current). + --> + <xsl:template name="get-node-path"> + <xsl:param name="Node" select="."/> + <xsl:for-each select="$Node"> + <xsl:for-each select="ancestor-or-self::node()"> + <xsl:choose> + <xsl:when test="name(.) = ''"> + <xsl:text>text()</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="concat('/', name(.))"/> + <xsl:choose> + <xsl:when test="@id"> + <xsl:text>[@id=</xsl:text> + <xsl:value-of select="@id"/> + <xsl:text>]</xsl:text> + </xsl:when> + <xsl:when test="position() > 1"> + <xsl:text>[</xsl:text><xsl:value-of select="position()"/><xsl:text>]</xsl:text> + </xsl:when> + </xsl:choose> + </xsl:otherwise> + </xsl:choose> + </xsl:for-each> + </xsl:for-each> + </xsl:template> + + <!-- + Debug/Diagnostics: Return error message prefix. + --> + <xsl:template name="error-prefix"> + <xsl:param name="Node" select="."/> + <xsl:text>error: </xsl:text> + <xsl:call-template name="get-node-path"> + <xsl:with-param name="Node" select="$Node"/> + </xsl:call-template> + <xsl:text>: </xsl:text> + </xsl:template> + + <!-- + Debug/Diagnostics: Print list of nodes (by default all children of current node). + --> + <xsl:template name="list-nodes"> + <xsl:param name="Nodes" select="node()"/> + <xsl:for-each select="$Nodes"> + <xsl:if test="position() != 1"> + <xsl:text>, </xsl:text> + </xsl:if> + <xsl:choose> + <xsl:when test="name(.) = ''"> + <xsl:text>text:text()</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="name(.)"/> + <xsl:if test="@id"> + <xsl:text>[@id=</xsl:text> + <xsl:value-of select="@id"/> + <xsl:text>]</xsl:text> + </xsl:if> + </xsl:otherwise> + </xsl:choose> + </xsl:for-each> + </xsl:template> + + <xsl:template name="check-children"> + <xsl:param name="Node" select="."/> + <xsl:param name="UnsupportedNodes" select="*"/> + <xsl:param name="SupportedNames" select="'none'"/> + <xsl:if test="count($UnsupportedNodes) != 0"> + <xsl:message terminate="yes"> + <xsl:call-template name="get-node-path"> + <xsl:with-param name="Node" select="$Node"/> + </xsl:call-template> + <!-- -->: error: Only <xsl:value-of select="$SupportedNames"/> are supported as children to <!-- --> + <xsl:value-of select="name($Node)"/> + <!-- --> +Unsupported children: <!-- --> + <xsl:call-template name="list-nodes"> + <xsl:with-param name="Nodes" select="$UnsupportedNodes"/> + </xsl:call-template> + </xsl:message> + </xsl:if> + </xsl:template> + +</xsl:stylesheet> + diff --git a/doc/manual/docbook-refentry-to-H-help.xsl b/doc/manual/docbook-refentry-to-H-help.xsl new file mode 100644 index 00000000..be624027 --- /dev/null +++ b/doc/manual/docbook-refentry-to-H-help.xsl @@ -0,0 +1,151 @@ +<?xml version="1.0"?> +<!-- + docbook-refentry-to-H-help.xsl: + XSLT stylesheet for generating command and sub-command + constants header for the built-in help. +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<xsl:stylesheet + version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:str="http://xsltsl.org/string" + > + + <xsl:import href="string.xsl"/> + + <xsl:output method="text" version="1.0" encoding="utf-8" indent="yes"/> + <xsl:strip-space elements="*"/> + + <xsl:param name="g_sMode" select="not-specified"/> + + + <!-- Default action, do nothing. --> + <xsl:template match="node()|@*"/> + + <!-- + Generate SCOPE enum for a refentry. We convert the + cmdsynopsisdiv/cmdsynopsis IDs into constants. + --> + <xsl:template match="refentry"> + <xsl:variable name="RefEntry" select="."/> + <xsl:variable name="sRefEntryId" select="@id"/> + <xsl:variable name="sBaseNm"> + <xsl:choose> + <xsl:when test="contains($sRefEntryId, '-')"> <!-- Multi level command. --> + <xsl:call-template name="str:to-upper"> + <xsl:with-param name="text" select="translate(substring-after($sRefEntryId, '-'), '-', '_')"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> <!-- Simple command. --> + <xsl:call-template name="str:to-upper"> + <xsl:with-param name="text" select="translate($sRefEntryId, '-', '_')"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + + <xsl:choose> + <!-- Generate subcommand enums and defines --> + <xsl:when test="$g_sMode = 'subcmd'"> + <!-- Start enum type and start off with the refentry id. --> + <xsl:text> +enum +{ +#define HELP_SCOPE_</xsl:text> + <xsl:value-of select="$sBaseNm"/> + <xsl:value-of select="substring(' ',1,56 - string-length($sBaseNm) - 11)"/> + <xsl:text> RT_BIT_64(HELP_SCOPE_</xsl:text><xsl:value-of select="$sBaseNm"/><xsl:text>_BIT) + HELP_SCOPE_</xsl:text><xsl:value-of select="$sBaseNm"/><xsl:text>_BIT = 0</xsl:text> + + <!-- Synopsis IDs --> + <xsl:for-each select="./refsynopsisdiv/cmdsynopsis[@id != concat('synopsis-', $sRefEntryId)]"> + <xsl:variable name="sSubNm"> + <xsl:text>HELP_SCOPE_</xsl:text> + <xsl:call-template name="str:to-upper"> + <xsl:with-param name="text" select="translate(substring-after(substring-after(@id, '-'), '-'), '-', '_')"/> + </xsl:call-template> + </xsl:variable> + <xsl:text>, +#define </xsl:text> + <xsl:value-of select="$sSubNm"/> + <xsl:value-of select="substring(' ',1,56 - string-length($sSubNm))"/> + <xsl:text> RT_BIT_64(</xsl:text><xsl:value-of select="$sSubNm"/><xsl:text>_BIT) + </xsl:text> + <xsl:value-of select="$sSubNm"/><xsl:text>_BIT</xsl:text> + </xsl:for-each> + + <!-- Add scoping info for refsect1 and refsect2 IDs that aren't part of the synopsis. --> + <xsl:for-each select=".//refsect1[@id] | .//refsect2[@id]"> + <xsl:variable name="sThisId" select="@id"/> + <xsl:if test="not($RefEntry[@id = $sThisId]) and not($RefEntry/refsynopsisdiv/cmdsynopsis[@id = concat('synopsis-', $sThisId)])"> + <xsl:variable name="sSubNm"> + <xsl:text>HELP_SCOPE_</xsl:text> + <xsl:choose> + <xsl:when test="contains($sRefEntryId, '-')"> <!-- Multi level command. --> + <xsl:call-template name="str:to-upper"> + <xsl:with-param name="text" select="translate(substring-after(@id, '-'), '-', '_')"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> <!-- Simple command. --> + <xsl:call-template name="str:to-upper"> + <xsl:with-param name="text" select="translate(@id, '-', '_')"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:text>, +#define </xsl:text> + <xsl:value-of select="$sSubNm"/> + <xsl:value-of select="substring(' ',1,56 - string-length($sSubNm))"/> + <xsl:text> RT_BIT_64(</xsl:text><xsl:value-of select="$sSubNm"/><xsl:text>_BIT) + </xsl:text> + <xsl:value-of select="$sSubNm"/><xsl:text>_BIT</xsl:text> + </xsl:if> + </xsl:for-each> + + <!-- Done - complete the enum. --> + <xsl:text>, + HELP_SCOPE_</xsl:text><xsl:value-of select="$sBaseNm"/><xsl:text>_END +}; +AssertCompile((int)HELP_SCOPE_</xsl:text><xsl:value-of select="$sBaseNm"/><xsl:text>_END >= 1); +AssertCompile((int)HELP_SCOPE_</xsl:text><xsl:value-of select="$sBaseNm"/><xsl:text>_END < 64); +AssertCompile(RT_BIT_64(HELP_SCOPE_</xsl:text><xsl:value-of select="$sBaseNm"/><xsl:text>_END - 1) & RTMSGREFENTRYSTR_SCOPE_MASK); +</xsl:text> + </xsl:when> + + <!-- Generate command enum value. --> + <xsl:when test="$g_sMode = 'cmd'"> + <xsl:text> HELP_CMD_</xsl:text><xsl:value-of select="$sBaseNm"/><xsl:text>, +</xsl:text> + </xsl:when> + + <!-- Shouldn't happen. --> + <xsl:otherwise> + <xsl:message terminate="yes">Bad or missing g_sMode string parameter value.</xsl:message> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + +</xsl:stylesheet> + diff --git a/doc/manual/docbook-refentry-to-manpage-preprocessing.xsl b/doc/manual/docbook-refentry-to-manpage-preprocessing.xsl new file mode 100644 index 00000000..97af4247 --- /dev/null +++ b/doc/manual/docbook-refentry-to-manpage-preprocessing.xsl @@ -0,0 +1,89 @@ +<?xml version="1.0"?> +<!-- + docbook-refentry-to-manpage-preprocessing.xsl: + XSLT stylesheet preprocessing remarks elements before + turning a refentry (manpage) into a unix manual page and + VBoxManage built-in help. +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<xsl:stylesheet + version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:str="http://xsltsl.org/string" + > + + <xsl:output method="xml" version="1.0" encoding="utf-8" indent="no"/> + + <!-- + The default action is to copy everything. + --> + <xsl:template match="node()|@*"> + <xsl:copy> + <xsl:apply-templates select="node()|@*"/> + </xsl:copy> + </xsl:template> + + <!-- + Execute synopsis copy remark (avoids duplication for complicated xml). + We strip the attributes off it. + --> + <xsl:template match="remark[@role = 'help-copy-synopsis']"> + <xsl:choose> + <xsl:when test="parent::refsect2"/> + <xsl:otherwise> + <xsl:message terminate="yes">Misplaced remark/@role=help-copy-synopsis element. +Only supported on: refsect2</xsl:message> + </xsl:otherwise> + </xsl:choose> + <xsl:variable name="sSrcId"> + <xsl:choose> + <xsl:when test="@condition"><xsl:value-of select="concat('synopsis-', @condition)"/></xsl:when> + <xsl:otherwise><xsl:value-of select="concat('synopsis-', ../@id)"/></xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:variable name="CmdSynopsis" select="/refentry/refsynopsisdiv/cmdsynopsis[@id = $sSrcId]"/> + <xsl:if test="not($CmdSynopsis)"> + <xsl:message terminate="yes">Could not find any cmdsynopsis with id=<xsl:value-of select="$sSrcId"/> in refsynopsisdiv.</xsl:message> + </xsl:if> + + <xsl:element name="cmdsynopsis"> + <xsl:apply-templates select="$CmdSynopsis/node()"/> + </xsl:element> + + </xsl:template> + + <!-- + Remove bits only intended for the manual. + --> + <xsl:template match="remark[@role='help-manual']"/> + + <!-- + Remove remarks without a role. + These are used for leaving questions and such while working with the documentation team. + --> + <xsl:template match="remark[not(@role)]"/> + + +</xsl:stylesheet> + diff --git a/doc/manual/docbook-refentry-to-manpage.xsl b/doc/manual/docbook-refentry-to-manpage.xsl new file mode 100644 index 00000000..40269f92 --- /dev/null +++ b/doc/manual/docbook-refentry-to-manpage.xsl @@ -0,0 +1,58 @@ +<?xml version="1.0"?> +<!-- + docbook-to-man.xsl: + XSLT stylesheet that renders a refentry into a troff manpage. +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<xsl:stylesheet + version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> + + <xsl:import href="manpages/docbook.xsl"/> + + <!-- + <xsl:output method="xml" version="1.0" encoding="utf-8" indent="yes"/> + <xsl:strip-space elements="*"/> + --> + + <!-- + Extract manual's date from an *info/pubdate node (cf. + get.refentry.date). Detect RCS Date keyword. + --> + <xsl:template match="pubdate"> + <xsl:choose> + <!-- careful with that keyword --> + <xsl:when test="starts-with(text(), concat('$', 'Date:'))"> + <!-- Fetch the ISO 8601 date from inside --> + <xsl:value-of select="substring(text(), 8, 10)"/> + </xsl:when> + <xsl:otherwise> + <!-- Use as-is --> + <xsl:value-of select="text()"/> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + +</xsl:stylesheet> + diff --git a/doc/manual/docbook-refentry-to-manual-overview.xsl b/doc/manual/docbook-refentry-to-manual-overview.xsl new file mode 100644 index 00000000..999b2801 --- /dev/null +++ b/doc/manual/docbook-refentry-to-manual-overview.xsl @@ -0,0 +1,74 @@ +<?xml version="1.0"?> +<!-- + docbook-refentry-to-manual-sect1.xsl: + XSLT stylesheet for nicking the refsynopsisdiv bit of a + refentry (manpage) for use in the command overview section + in the user manual. +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<xsl:stylesheet + version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + > + + <xsl:output method="xml" version="1.0" encoding="utf-8" indent="yes"/> + <xsl:strip-space elements="*"/> + + +<!-- Base operation is to copy. --> +<xsl:template match="node()|@*"> + <xsl:copy> + <xsl:apply-templates select="node()|@*"/> + </xsl:copy> +</xsl:template> + +<!-- + The refentry element is the top level one. We only process the + refsynopsisdiv sub element within it, since that is all we want. + --> +<xsl:template match="refentry"> + <xsl:apply-templates select="refsynopsisdiv"/> +</xsl:template> + +<!-- + Combine all cmdsynopsis lines into a bunch of commands. + --> +<xsl:template match="refsynopsisdiv"> + <xsl:if test="not(cmdsynopsis)"> + <xsl:message terminate="yes">What? No cmdsynopsis in the refsynopsisdiv?</xsl:message> + </xsl:if> + <xsl:element name="cmdsynopsis"> + <xsl:attribute name="id"><xsl:value-of select="/refentry/@id"/><xsl:text>-overview</xsl:text></xsl:attribute> + <xsl:for-each select="cmdsynopsis"> + <xsl:copy-of select="node()"/> + </xsl:for-each> + </xsl:element> +</xsl:template> + +<!-- Remove all remarks (for now). --> +<xsl:template match="remark"/> + + +</xsl:stylesheet> + diff --git a/doc/manual/docbook-refentry-to-manual-sect1.xsl b/doc/manual/docbook-refentry-to-manual-sect1.xsl new file mode 100644 index 00000000..01d0cfad --- /dev/null +++ b/doc/manual/docbook-refentry-to-manual-sect1.xsl @@ -0,0 +1,183 @@ +<?xml version="1.0"?> +<!-- + docbook-refentry-to-manual-sect1.xsl: + XSLT stylesheet for transforming a refentry (manpage) + to a sect1 for the user manual. +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<xsl:stylesheet + version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:str="http://xsltsl.org/string" + > + + <xsl:import href="string.xsl"/> + + <xsl:output method="xml" version="1.0" encoding="utf-8" indent="yes"/> + <xsl:strip-space elements="*"/> + + +<!-- - - - - - - - - - - - - - - - - - - - - - - + global XSLT variables + - - - - - - - - - - - - - - - - - - - - - - --> + + + +<!-- - - - - - - - - - - - - - - - - - - - - - - + base operation is to copy. + - - - - - - - - - - - - - - - - - - - - - - --> + +<xsl:template match="node()|@*"> + <xsl:copy> + <xsl:apply-templates select="node()|@*"/> + </xsl:copy> +</xsl:template> + + +<!-- - - - - - - - - - - - - - - - - - - - - - - + + - - - - - - - - - - - - - - - - - - - - - - --> + +<!-- rename refentry to sect1 --> +<xsl:template match="refentry"> + <xsl:element name="sect1"> + <xsl:attribute name="condition">refentry</xsl:attribute> + <xsl:apply-templates select="node()|@*"/> + </xsl:element> +</xsl:template> + +<!-- Remove refentryinfo, keeping the title element. --> +<xsl:template match="refentryinfo"> + <xsl:if test="./title"> + <xsl:copy-of select="./title"/> + </xsl:if> +</xsl:template> + +<!-- Morph refnamediv into a brief description. --> +<xsl:template match="refnamediv"> + <xsl:element name="para"> + <xsl:call-template name="capitalize"> + <xsl:with-param name="text" select="normalize-space(./refpurpose)"/> + </xsl:call-template> + <xsl:text>.</xsl:text> + </xsl:element> +</xsl:template> + +<!-- Morph the refsynopsisdiv part into a synopsis section. --> +<xsl:template match="refsynopsisdiv"> + <xsl:if test="name(*[1]) != 'cmdsynopsis'"><xsl:message terminate="yes">Expected refsynopsisdiv to start with cmdsynopsis</xsl:message></xsl:if> + <xsl:if test="title"><xsl:message terminate="yes">No title element supported in refsynopsisdiv</xsl:message></xsl:if> + + <xsl:element name="sect2"> + <xsl:attribute name="role">not-in-toc</xsl:attribute> + <xsl:attribute name="condition">refsynopsisdiv</xsl:attribute> + <xsl:element name="title"> + <xsl:text>Synopsis</xsl:text> + </xsl:element> + <xsl:apply-templates /> + </xsl:element> + +</xsl:template> + +<!-- refsect1 -> sect2 --> +<xsl:template match="refsect1"> + <xsl:if test="not(title)"><xsl:message terminate="yes">refsect1 requires title</xsl:message></xsl:if> + <xsl:element name="sect2"> + <xsl:attribute name="role">not-in-toc</xsl:attribute> + <xsl:attribute name="condition">refsect1</xsl:attribute> + <xsl:if test="@id"> + <xsl:attribute name="id"><xsl:value-of select="@id"/></xsl:attribute> + </xsl:if> + <xsl:apply-templates /> + </xsl:element> +</xsl:template> + +<!-- refsect2 -> sect3 --> +<xsl:template match="refsect2"> + <xsl:if test="not(title)"><xsl:message terminate="yes">refsect2 requires title</xsl:message></xsl:if> + <xsl:element name="sect3"> + <xsl:attribute name="role">not-in-toc</xsl:attribute> + <xsl:attribute name="condition">refsect2</xsl:attribute> + <xsl:if test="@id"> + <xsl:attribute name="id"><xsl:value-of select="@id"/></xsl:attribute> + </xsl:if> + <xsl:apply-templates /> + </xsl:element> +</xsl:template> + +<!-- refsect3 -> sect4 --> +<xsl:template match="refsect3"> + <xsl:if test="not(title)"><xsl:message terminate="yes">refsect3 requires title</xsl:message></xsl:if> + <xsl:element name="sect4"> + <xsl:attribute name="role">not-in-toc</xsl:attribute> + <xsl:attribute name="condition">refsect3</xsl:attribute> + <xsl:if test="@id"> + <xsl:attribute name="id"><xsl:value-of select="@id"/></xsl:attribute> + </xsl:if> + <xsl:apply-templates /> + </xsl:element> +</xsl:template> + + +<!-- Remove refmeta. --> +<xsl:template match="refmeta"/> + +<!-- + remark extensions: + --> +<!-- Default: remove all remarks. --> +<xsl:template match="remark"/> + +<!-- help-manual - stuff that should only be included in the manual. --> +<xsl:template match="remark[@role = 'help-manual']"> + <xsl:apply-templates/> +</xsl:template> + +<!-- help-copy-synopsis - used in refsect2 to copy synopsis from the refsynopsisdiv. --> +<xsl:template match="remark[@role = 'help-copy-synopsis']"> + <xsl:if test="not(parent::refsect2)"> + <xsl:message terminate="yes">The help-copy-synopsis remark is only applicable in refsect2.</xsl:message> + </xsl:if> + <xsl:variable name="sSrcId" select="concat('synopsis-',../@id)"/> + <xsl:if test="not(/refentry/refsynopsisdiv/cmdsynopsis[@id = $sSrcId])"> + <xsl:message terminate="yes">Could not find any cmdsynopsis with id=<xsl:value-of select="$sSrcId"/> in refsynopsisdiv.</xsl:message> + </xsl:if> + <xsl:element name="cmdsynopsis"> + <xsl:copy-of select="/refentry/refsynopsisdiv/cmdsynopsis[@id = $sSrcId]/node()"/> + </xsl:element> +</xsl:template> + +<!-- + Captializes the given text. + --> +<xsl:template name="capitalize"> + <xsl:param name="text"/> + <xsl:call-template name="str:to-upper"> + <xsl:with-param name="text" select="substring($text,1,1)"/> + </xsl:call-template> + <xsl:value-of select="substring($text,2)"/> +</xsl:template> + +</xsl:stylesheet> + diff --git a/doc/manual/docbook2latex.xsl b/doc/manual/docbook2latex.xsl new file mode 100644 index 00000000..101f6a80 --- /dev/null +++ b/doc/manual/docbook2latex.xsl @@ -0,0 +1,1305 @@ +<?xml version="1.0"?> + +<!-- + docbook2latex.xslt: + translates a DocBook XML source into a LaTeX source file, + which can be processed with pdflatex to produce a + pretty PDF file. + + Note: In the LaTeX output, this XSLT encodes all quotes + with \QUOTE{} commands, which are not defined in this + file. This is because XSLT does not support regular + expressions natively and therefore it is rather difficult + to implement proper "pretty quotes" (different glyphs for + opening and closing quotes) in XSLT. The doc/manual/ + makefile solves this by running sed over the LaTeX source + once more, replacing all \QUOTE{} commands with + \OQ{} and \CQ{} commands, which _are_ defined to the + pretty quotes for English in the LaTeX output generated + by this XSLT (see below). +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<xsl:stylesheet + version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:xsd="http://www.w3.org/2001/XMLSchema" + xmlns:str="http://xsltsl.org/string" +> + + <xsl:import href="string.xsl"/> + <xsl:import href="common-formatcfg.xsl"/> + + <xsl:variable name="g_nlsChapter"> + <xsl:choose> + <xsl:when test="$TARGETLANG='de_DE'">Kapitel</xsl:when> + <xsl:when test="$TARGETLANG='fr_FR'">chapitre</xsl:when> + <xsl:when test="$TARGETLANG='en_US'">chapter</xsl:when> + <xsl:otherwise> + <xsl:message terminate="yes"><xsl:value-of select="concat('Invalid language ', $TARGETLANG)" /></xsl:message> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + + <xsl:variable name="g_nlsPage"> + <xsl:choose> + <xsl:when test="$TARGETLANG='de_DE'">auf Seite</xsl:when> + <xsl:when test="$TARGETLANG='fr_FR'">page</xsl:when> + <xsl:when test="$TARGETLANG='en_US'">page</xsl:when> + <xsl:otherwise> + <xsl:message terminate="yes"><xsl:value-of select="concat('Invalid language ', $TARGETLANG)" /></xsl:message> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + + <xsl:variable name="g_nlsNote"> + <xsl:choose> + <xsl:when test="$TARGETLANG='de_DE'">Hinweis</xsl:when> + <xsl:when test="$TARGETLANG='fr_FR'">Note</xsl:when> + <xsl:when test="$TARGETLANG='en_US'">Note</xsl:when> + <xsl:otherwise> + <xsl:message terminate="yes"><xsl:value-of select="concat('Invalid language ', $TARGETLANG)" /></xsl:message> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + + <xsl:variable name="g_nlsWarning"> + <xsl:choose> + <xsl:when test="$TARGETLANG='de_DE'">Warnung</xsl:when> + <xsl:when test="$TARGETLANG='fr_FR'">Avertissement</xsl:when> + <xsl:when test="$TARGETLANG='en_US'">Warning</xsl:when> + <xsl:otherwise> + <xsl:message terminate="yes"><xsl:value-of select="concat('Invalid language ', $TARGETLANG)" /></xsl:message> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + + <!-- command synopsis --> + <xsl:variable name="arg.rep.repeat.str.tex">\ldots{}</xsl:variable> + <xsl:variable name="arg.or.sep.tex"> |~</xsl:variable> + + <xsl:output method="text"/> + + <xsl:strip-space elements="*"/> + <xsl:preserve-space elements="para"/> + + <xsl:template match="/book"> + <xsl:text> +\documentclass[oneside,a4paper,10pt,DIV10]{scrbook} +\usepackage{geometry} +\geometry{top=3cm,bottom=4cm} +\usepackage[T1]{fontenc} +\usepackage{tabulary} +\usepackage[pdftex, + a4paper, + colorlinks=true, + linkcolor=blue, + urlcolor=darkgreen, + bookmarksnumbered, + bookmarksopen=true, + bookmarksopenlevel=0, + hyperfootnotes=false, + plainpages=false, + pdfpagelabels + ]{hyperref} + +\usepackage{nameref} +\usepackage{graphicx} +\usepackage{hyperref} +\usepackage{fancybox} +\usepackage{alltt} +\usepackage{color} +\usepackage{scrextend} +\definecolor{darkgreen}{rgb}{0,0.6,0} +\tymin=21pt + +</xsl:text> + <xsl:if test="$TARGETLANG='de_DE'">\usepackage[ngerman]{babel} \PrerenderUnicode{ü}</xsl:if> +<!-- <xsl:if test="$TARGETLANG='fr_FR'">\usepackage[french]{babel} \FrenchItemizeSpacingfalse \renewcommand{\FrenchLabelItem}{\textbullet}</xsl:if> + this command is no longer understood by TexLive2008 + --> + <xsl:text> + +% use Palatino as serif font: +% \usepackage{mathpazo} +\usepackage{charter} +% use Helvetica as sans-serif font: +\usepackage{helvet} + +% use Bera Mono (a variant of Bitstream Vera Mono) as typewriter font +% (requires texlive-fontsextra) +\usepackage[scaled]{beramono} +% previously: use Courier as typewriter font: +% \usepackage{courier} + +\definecolor{colNote}{rgb}{0,0,0} +\definecolor{colWarning}{rgb}{0,0,0} +\definecolor{colScreenFrame}{rgb}{0,0,0} +\definecolor{colScreenText}{rgb}{0,0,0} + +% number headings down to this level +\setcounter{secnumdepth}{3} +% more space for the section numbers +\makeatletter +\renewcommand*\l@section{\@dottedtocline{1}{1.5em}{2.9em}} +\renewcommand*\l@subsection{\@dottedtocline{2}{4.4em}{3.8em}} +\renewcommand*\l@subsubsection{\@dottedtocline{3}{8.2em}{3.8em}} +\renewcommand*\@pnumwidth{1.7em} +\renewcommand*\@tocrmarg{5.0em} +\makeatother + +% more tolerance at 2nd wrap stage: +\tolerance = 1000 +% allow 3rd wrap stage: +\emergencystretch = 10pt +% no Schusterjungen: +\clubpenalty = 10000 +% no Hurenkinder: +\widowpenalty = 10000 +\displaywidowpenalty = 10000 +% max pdf compression: +\pdfcompresslevel9 + +% opening and closing quotes: the OQ and CQ macros define this (and the makefile employs some sed magic also) +</xsl:text> + <xsl:choose> + <xsl:when test="$TARGETLANG='de_DE'"> + <xsl:text>\newcommand\OQ{\texorpdfstring{\glqq}{"}} \newcommand\CQ{\texorpdfstring{\grqq}{"}} </xsl:text> + </xsl:when> + <xsl:when test="$TARGETLANG='fr_FR'"> + <xsl:text>\newcommand\OQ{\texorpdfstring{``}{"}} \newcommand\CQ{\texorpdfstring{''}{"}} </xsl:text> + </xsl:when> + <xsl:when test="$TARGETLANG='en_US'"> + <xsl:text>\newcommand\OQ{\texorpdfstring{``}{"}} \newcommand\CQ{\texorpdfstring{''}{"}} </xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:message terminate="yes"><xsl:value-of select="concat('Invalid language ', $TARGETLANG)" /></xsl:message> + </xsl:otherwise> + </xsl:choose> + + <xsl:apply-templates /> + + <xsl:text> +\end{sloppypar} +\end{document} + </xsl:text> + + </xsl:template> + + <xsl:template match="bookinfo"> + <xsl:apply-templates /> + <xsl:text>
\newcommand\docbookbookinfocopyright{Copyright \copyright{} \docbookbookinfocopyrightyear{} \docbookbookinfocopyrightholder{}}
 +\author{ \docbooktitleedition \\ % +\\ % +</xsl:text> + <xsl:if test="//bookinfo/address"> + <xsl:text>\docbookbookinfoaddress \\ % +\\ % +</xsl:text> + </xsl:if> + <xsl:text>\docbookbookinfocopyright \\ % +} + +\title{\docbooktitle \\ +\docbooksubtitle} +% \subtitle{\docbooksubtitle} +\hypersetup{pdfauthor=\docbookcorpauthor} +\hypersetup{pdftitle=\docbooktitle{} \docbooksubtitle{}} + +\hyphenation{da-ta-ba-ses} +\hyphenation{deb-conf} +\hyphenation{VirtualBox} + +\begin{document} +\frontmatter +% bird/2018-05-14: Use sloppypar so we don't push path names and other long words +% thru the right margin. TODO: Find better solution? microtype? +\begin{sloppypar} +% \maketitle +%\begin{titlepage} +\thispagestyle{empty} +\begin{minipage}{\textwidth} +\begin{center} +\includegraphics[width=4cm]{images/vboxlogo.png} +\end{center}% +\vspace{10mm} + +{\fontsize{40pt}{40pt}\selectfont\rmfamily\bfseries% +\begin{center} +\docbooktitle +\end{center}% +\vspace{10mm} +} + +{\fontsize{30pt}{30pt}\selectfont\rmfamily\bfseries% +\begin{center} +\docbooksubtitle +\end{center}% +\vspace{10mm} +} + +{\fontsize{16pt}{20pt}\selectfont\rmfamily% +\begin{center} +</xsl:text> + <xsl:if test="//bookinfo/othercredit"> + <xsl:text>\docbookbookinfoothercreditcontrib{}: \docbookbookinfoothercreditfirstname{} \docbookbookinfoothercreditsurname + +\vspace{8mm} +</xsl:text> + </xsl:if> + <xsl:text>\docbooktitleedition + +\vspace{2mm} + +\docbookbookinfocopyright + +\vspace{2mm} + +\docbookbookinfoaddress +\end{center}% +} + +%\end{titlepage} +\end{minipage} + +\tableofcontents + </xsl:text> + </xsl:template> + + <xsl:template match="subtitle"> + <xsl:choose> + <xsl:when test="name(..)='bookinfo'"> + <xsl:text>\newcommand\docbooksubtitle{</xsl:text> + <xsl:apply-templates /> + <xsl:text>}</xsl:text> + </xsl:when> + </xsl:choose> + </xsl:template> + + <!-- Determins the section depth, returning a number 1,2,3,4,5,6,7,... --> + <xsl:template name="get-section-level"> + <xsl:param name="a_Node" select=".."/> + <xsl:for-each select="$a_Node"> <!-- makes it current --> + <xsl:choose> + <xsl:when test="self::sect1"><xsl:text>1</xsl:text></xsl:when> + <xsl:when test="self::sect2"><xsl:text>2</xsl:text></xsl:when> + <xsl:when test="self::sect3"><xsl:text>3</xsl:text></xsl:when> + <xsl:when test="self::sect4"><xsl:text>4</xsl:text></xsl:when> + <xsl:when test="self::sect5"><xsl:text>5</xsl:text></xsl:when> + <xsl:when test="self::section"> + <xsl:value-of select="count(ancestor::section) + 1"/> + </xsl:when> + <xsl:when test="self::simplesect"> + <xsl:variable name="tmp"> + <xsl:call-template name="get-section-level"> + <xsl:with-param name="a_Node" select="parent::*"/> + </xsl:call-template> + </xsl:variable> + <xsl:value-of select="$tmp + 1"/> + </xsl:when> + <xsl:when test="self::preface"><xsl:text>0</xsl:text></xsl:when> + <xsl:when test="self::chapter"><xsl:text>0</xsl:text></xsl:when> + <xsl:when test="self::appendix"><xsl:text>0</xsl:text></xsl:when> + <xsl:when test="self::article"><xsl:text>0</xsl:text></xsl:when> + <xsl:otherwise> + <xsl:message terminate="yes">get-section-level was called on non-section element: <xsl:value-of select="."/> </xsl:message> + </xsl:otherwise> + </xsl:choose> + </xsl:for-each> + </xsl:template> + + <!-- + Inserts \hypertarget{@id} that can be referenced via the /A "nameddest=@id" + command line or #nameddest=@id URL parameter. + + TODO: The placement of the target could be improved on. The raisebox + stuff is a crude hack to make it a little more acceptable. --> + <xsl:template name="title-wrapper"> + <xsl:param name="texcmd" select="concat('\',name(..))"/> + <xsl:param name="refid" select="../@id"/> + <xsl:param name="role" select="../@role"/> + + <xsl:call-template name="xsltprocNewlineOutputHack"/> + <xsl:if test="$texcmd='\chapter' and (name(../preceding-sibling::*[1])='preface' or name(../preceding-sibling::*[1])='bookinfo')"> + <xsl:text>\mainmatter
</xsl:text> + </xsl:if> + <xsl:choose> + <xsl:when test="$refid"> + <xsl:text>
</xsl:text> + <xsl:value-of select="$texcmd"/> + <xsl:if test="not(contains($texcmd, '*'))"> + <xsl:text>[</xsl:text> <!-- for toc --> + <xsl:apply-templates /> + <xsl:text>]</xsl:text> + </xsl:if> + <xsl:text>{</xsl:text> <!-- for doc --> + <xsl:text>\raisebox{\ht\strutbox}{\hypertarget{</xsl:text> + <xsl:value-of select="$refid"/> + <xsl:text>}{}}</xsl:text> + <xsl:apply-templates /> + <xsl:text>}</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>
</xsl:text><xsl:value-of select="$texcmd"/><xsl:text>{</xsl:text> + <xsl:apply-templates /> + <xsl:text>}</xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <xsl:template match="title"> + <xsl:variable name="refid" select="../@id" /> + <xsl:choose> + <xsl:when test="name(..)='bookinfo'"> + <xsl:text>\newcommand\docbooktitle{</xsl:text> + <xsl:apply-templates /> + <xsl:text>}</xsl:text> + </xsl:when> + <xsl:when test="name(..)='chapter'"> + <xsl:call-template name="title-wrapper"/> + </xsl:when> + <xsl:when test="name(..)='preface'"> + <xsl:call-template name="title-wrapper"> + <xsl:with-param name="texcmd">\chapter</xsl:with-param> + </xsl:call-template> + </xsl:when> + <xsl:when test="name(..)='sect1'"> + <xsl:call-template name="title-wrapper"> + <xsl:with-param name="texcmd">\section</xsl:with-param> + </xsl:call-template> + </xsl:when> + <xsl:when test="parent::sect2[@role='not-in-toc'] or parent::refsect1 or (parent::section and count(ancestor::section) = 2)"> + <xsl:call-template name="title-wrapper"> + <xsl:with-param name="texcmd">\subsection*</xsl:with-param> + </xsl:call-template> + </xsl:when> + <xsl:when test="name(..)='sect2'"> + <xsl:call-template name="title-wrapper"> + <xsl:with-param name="texcmd">\subsection</xsl:with-param> + </xsl:call-template> + </xsl:when> + <xsl:when test="parent::sect3[@role='not-in-toc'] or parent::refsect2 or (parent::section and count(ancestor::section) = 3)"> + <xsl:call-template name="title-wrapper"> + <xsl:with-param name="texcmd">\subsubsection*</xsl:with-param> + </xsl:call-template> + </xsl:when> + <xsl:when test="name(..)='sect3'"> + <xsl:call-template name="title-wrapper"> + <xsl:with-param name="texcmd">\subsubsection</xsl:with-param> + </xsl:call-template> + </xsl:when> + <xsl:when test="parent::sect4[@role='not-in-toc'] or parent::refsect3 or (parent::section and count(ancestor::section) = 4)"> + <xsl:call-template name="title-wrapper"> + <xsl:with-param name="texcmd">\paragraph*</xsl:with-param> + </xsl:call-template> + </xsl:when> + <xsl:when test="name(..)='sect4'"> + <xsl:call-template name="title-wrapper"> + <xsl:with-param name="texcmd">\paragraph</xsl:with-param> + </xsl:call-template> + </xsl:when> + <xsl:when test="parent::sect5[@role='not-in-toc'] or parent::refsect4 or (parent::section and count(ancestor::section) = 5)"> + <xsl:call-template name="title-wrapper"> + <xsl:with-param name="texcmd">\subparagraph*</xsl:with-param> + </xsl:call-template> + </xsl:when> + <xsl:when test="name(..)='sect5'"> + <xsl:call-template name="title-wrapper"> + <xsl:with-param name="texcmd">\subparagraph</xsl:with-param> + </xsl:call-template> + </xsl:when> + <xsl:when test="name(..)='appendix'"> + <xsl:call-template name="title-wrapper"> + <xsl:with-param name="texcmd">\chapter</xsl:with-param> + </xsl:call-template> + </xsl:when> + <xsl:when test="name(..)='glossdiv'"> + <xsl:call-template name="title-wrapper"> + <xsl:with-param name="texcmd">\section*</xsl:with-param> + </xsl:call-template> + </xsl:when> + + <xsl:when test="parent::simplesect"> + <xsl:if test="../@role"> + <xsl:message terminate="yes">Role not allowed with simplesect: <xsl:value-of select="../@role"/></xsl:message> + </xsl:if> + <xsl:variable name="level"> + <xsl:call-template name="get-section-level"> + <xsl:with-param name="a_Node" select=".."/> + </xsl:call-template> + </xsl:variable> + <xsl:choose> + <xsl:when test="$level = 1"> + <xsl:call-template name="title-wrapper"><xsl:with-param name="texcmd">\section*</xsl:with-param></xsl:call-template> + </xsl:when> + <xsl:when test="$level = 2"> + <xsl:call-template name="title-wrapper"><xsl:with-param name="texcmd">\subsection*</xsl:with-param></xsl:call-template> + </xsl:when> + <xsl:when test="$level = 3"> + <xsl:call-template name="title-wrapper"><xsl:with-param name="texcmd">\subsubsection*</xsl:with-param></xsl:call-template> + </xsl:when> + <xsl:when test="$level = 4"> + <xsl:call-template name="title-wrapper"><xsl:with-param name="texcmd">\paragraph*</xsl:with-param></xsl:call-template> + </xsl:when> + <xsl:when test="$level = 5"> + <xsl:call-template name="title-wrapper"><xsl:with-param name="texcmd">\subparagraph*</xsl:with-param></xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:message terminate="yes">Unsupported simplesect/title depth: <xsl:value-of select="$level"/></xsl:message> + </xsl:otherwise> + </xsl:choose> + </xsl:when> + + </xsl:choose> + <xsl:if test="$refid"> + <xsl:value-of select="concat('
\label{', $refid, '}')" /> + </xsl:if> + <xsl:text>
</xsl:text> + </xsl:template> + + <xsl:template match="edition"> + <xsl:choose> + <xsl:when test="name(..)='bookinfo'"> + <xsl:text>\newcommand\docbooktitleedition{</xsl:text> + <xsl:apply-templates /> + <xsl:text>}
</xsl:text> + </xsl:when> + </xsl:choose> + </xsl:template> + + <xsl:template match="corpauthor"> + <xsl:choose> + <xsl:when test="name(..)='bookinfo'"> + <xsl:text>\newcommand\docbookcorpauthor{</xsl:text> + <xsl:apply-templates /> + <xsl:text>}
</xsl:text> + </xsl:when> + </xsl:choose> + </xsl:template> + + <xsl:template match="address"> + <xsl:choose> + <xsl:when test="name(..)='bookinfo'"> + <xsl:text>\newcommand\docbookbookinfoaddress{</xsl:text> + <xsl:apply-templates /> + <xsl:text>}
</xsl:text> + </xsl:when> + </xsl:choose> + </xsl:template> + + <xsl:template match="year"> + <xsl:choose> + <xsl:when test="name(..)='copyright'"> + <xsl:text>\newcommand\docbookbookinfocopyrightyear{</xsl:text> + <xsl:apply-templates /> + <xsl:text>}
</xsl:text> + </xsl:when> + </xsl:choose> + </xsl:template> + + <xsl:template match="holder"> + <xsl:choose> + <xsl:when test="name(..)='copyright'"> + <xsl:text>\newcommand\docbookbookinfocopyrightholder{</xsl:text> + <xsl:apply-templates /> + <xsl:text>}
</xsl:text> + </xsl:when> + </xsl:choose> + </xsl:template> + + <xsl:template match="firstname"> + <xsl:choose> + <xsl:when test="name(..)='othercredit'"> + <xsl:text>\newcommand\docbookbookinfoothercreditfirstname{</xsl:text> + <xsl:apply-templates /> + <xsl:text>}
</xsl:text> + </xsl:when> + </xsl:choose> + </xsl:template> + + <xsl:template match="surname"> + <xsl:choose> + <xsl:when test="name(..)='othercredit'"> + <xsl:text>\newcommand\docbookbookinfoothercreditsurname{</xsl:text> + <xsl:apply-templates /> + <xsl:text>}
</xsl:text> + </xsl:when> + </xsl:choose> + </xsl:template> + + <xsl:template match="contrib"> + <xsl:choose> + <xsl:when test="name(..)='othercredit'"> + <xsl:text>\newcommand\docbookbookinfoothercreditcontrib{</xsl:text> + <xsl:apply-templates /> + <xsl:text>}
</xsl:text> + </xsl:when> + </xsl:choose> + </xsl:template> + + <xsl:template match="glossary"> + <xsl:text>

\backmatter
\chapter{Glossary}
</xsl:text> + <xsl:apply-templates /> + </xsl:template> + + <xsl:template match="para"> + <xsl:if test="not(name(..)='footnote' or name(..)='note' or name(..)='warning' or name(..)='entry' or (name(../..)='varlistentry' and position()=1))"> + <xsl:text>

</xsl:text> + </xsl:if> + <xsl:apply-templates /> + </xsl:template> + + <xsl:template match="note"> + <xsl:value-of select="concat('

\vspace{.2cm}

\begin{center}\fbox{\begin{minipage}[c]{0.9\textwidth}\color{colNote}\textbf{', $g_nlsNote, ':} ')" /> + <xsl:apply-templates /> + <xsl:text>\end{minipage}}\end{center}

\vspace{.2cm}

</xsl:text> + </xsl:template> + + <xsl:template match="warning"> + <xsl:value-of select="concat('

\vspace{.2cm}

\begin{center}\fbox{\begin{minipage}[c]{0.9\textwidth}\color{colWarning}\textbf{', $g_nlsWarning, ':} ')" /> + <xsl:apply-templates /> + <xsl:text>\end{minipage}}\end{center}

\vspace{.2cm}

</xsl:text> + </xsl:template> + + <xsl:template match="screen"> + <xsl:text>

{\footnotesize\begin{alltt}
</xsl:text> + <xsl:apply-templates /> + <xsl:text>
\end{alltt}}
</xsl:text> + </xsl:template> + + <xsl:template match="programlisting"> + <xsl:text>

{\small\begin{alltt}
</xsl:text> + <xsl:apply-templates /> + <xsl:text>
\end{alltt}}
</xsl:text> + </xsl:template> + + <xsl:template match="footnote"> + <xsl:text>\footnote{</xsl:text> + <xsl:apply-templates /> + <xsl:text>}</xsl:text> + </xsl:template> + + <xsl:template match="tgroup"> + <xsl:choose> + <xsl:when test="@style='verywide'"> + <xsl:text>

{\small\begin{center}
\begin{tabulary}{1.1\textwidth}[]</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>

{\small\begin{center}
\begin{tabulary}{.9\textwidth}[]</xsl:text> + </xsl:otherwise> + </xsl:choose> + <xsl:text>{</xsl:text> + <xsl:choose> + <xsl:when test="@cols='1'"> + <xsl:text>|L|</xsl:text> + </xsl:when> + <xsl:when test="@cols='2'"> + <xsl:text>|L|L|</xsl:text> + </xsl:when> + <xsl:when test="@cols='3'"> + <xsl:text>|L|L|L|</xsl:text> + </xsl:when> + <xsl:when test="@cols='4'"> + <xsl:text>|L|L|L|L|</xsl:text> + </xsl:when> + <xsl:when test="@cols='5'"> + <xsl:text>|L|L|L|L|L|</xsl:text> + </xsl:when> + <xsl:when test="@cols='6'"> + <xsl:text>|L|L|L|L|L|L|</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:message terminate="yes">Unsupported number of columns (<xsl:value-of select="@cols"/>), fix document or converter</xsl:message> + </xsl:otherwise> + </xsl:choose> + <xsl:text>}
\hline
</xsl:text> + <xsl:apply-templates /> + <xsl:text>
\end{tabulary}
\end{center}}
</xsl:text> + </xsl:template> + + <xsl:template match="row"> + <xsl:apply-templates /> + <xsl:text>
\\ \hline
</xsl:text> + </xsl:template> + + <xsl:template match="entry"> + <xsl:if test="not(position()=1)"> + <xsl:text> & </xsl:text> + </xsl:if> + <xsl:apply-templates /> + </xsl:template> + + <xsl:template match="itemizedlist"> + <xsl:call-template name="xsltprocNewlineOutputHack"/> + <xsl:text>
\begin{itemize}
</xsl:text> + <xsl:if test="@spacing = 'compact'"> + <xsl:text> \setlength{\parskip}{0pt}
</xsl:text> + <xsl:text> \setlength{\itemsep}{0pt}
</xsl:text> + <xsl:text> \setlength{\topsep}{0pt}
</xsl:text> + <xsl:text> \setlength{\parsep}{0pt}
</xsl:text> + <xsl:text> \setlength{\partopsep}{0pt}
</xsl:text> + </xsl:if> + <xsl:apply-templates /> + <xsl:text>
\end{itemize}
</xsl:text> + </xsl:template> + + <xsl:template match="orderedlist"> + <xsl:call-template name="xsltprocNewlineOutputHack"/> + <xsl:text>
\begin{enumerate}
</xsl:text> + <xsl:if test="@spacing = 'compact'"> + <xsl:text> \setlength{\parskip}{0pt}
</xsl:text> + <xsl:text> \setlength{\itemsep}{0pt}
</xsl:text> + <xsl:text> \setlength{\topsep}{0pt}
</xsl:text> + <xsl:text> \setlength{\parsep}{0pt}
</xsl:text> + <xsl:text> \setlength{\partopsep}{0pt}
</xsl:text> + </xsl:if> + <xsl:apply-templates /> + <xsl:text>
\end{enumerate}
</xsl:text> + </xsl:template> + + <xsl:template match="variablelist"> + <xsl:call-template name="xsltprocNewlineOutputHack"/> + <xsl:text>
\begin{description}
</xsl:text> + <xsl:if test="@spacing = 'compact'"> + <xsl:text> \setlength{\parskip}{0pt}
</xsl:text> + <xsl:text> \setlength{\itemsep}{0pt}
</xsl:text> + <xsl:text> \setlength{\topsep}{0pt}
</xsl:text> + <xsl:text> \setlength{\parsep}{0pt}
</xsl:text> + <xsl:text> \setlength{\partopsep}{0pt}
</xsl:text> + </xsl:if> + <xsl:apply-templates /> + <xsl:text>
\end{description}
</xsl:text> + </xsl:template> + + <xsl:template match="varlistentry"> + <xsl:if test="not(./term) or not(./listitem) or count(./listitem) != 1"> + <xsl:message terminate="yes">Expected at least one term and one listitem element in the varlistentry.</xsl:message> + </xsl:if> + <xsl:text>

\item[{\parbox[t]{\linewidth}{\raggedright </xsl:text> + <xsl:apply-templates select="./term[1]"/> + <xsl:for-each select="./term[position() > 1]"> + <xsl:text>\\
 </xsl:text> + <xsl:apply-templates select="."/> + </xsl:for-each> + <xsl:text>}}]\hfill\\</xsl:text> + <xsl:apply-templates select="listitem/*"/> + </xsl:template> + + <xsl:template match="listitem"> + <xsl:text>

\item </xsl:text> + <xsl:apply-templates /> + <xsl:text>
</xsl:text> + </xsl:template> + + <xsl:template match="glossterm"> + <xsl:variable name="refid" select="(@id)" /> + <xsl:if test="$refid"> + <xsl:value-of select="concat('
\label{', $refid, '}')" /> + </xsl:if> + <xsl:text>

\item[</xsl:text> + <xsl:apply-templates /> + <xsl:text>]</xsl:text> + </xsl:template> + + <xsl:template match="glosslist | glossdiv"> + <xsl:text>

\begin{description}
</xsl:text> + <xsl:apply-templates /> + <xsl:text>
\end{description}
</xsl:text> + </xsl:template> + + <xsl:template match="superscript"> + <xsl:variable name="contents"> + <xsl:apply-templates /> + </xsl:variable> + <xsl:value-of select="concat('\texorpdfstring{\textsuperscript{', $contents, '}}{', $contents, '}')" /> + </xsl:template> + + <xsl:template match="emphasis"> + <xsl:choose> + <xsl:when test="@role='bold'"> + <xsl:text>\textbf{</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>\textit{</xsl:text> + </xsl:otherwise> + </xsl:choose> + <xsl:apply-templates /> + <xsl:text>}</xsl:text> + </xsl:template> + + <xsl:template match="computeroutput | code"> + <xsl:text>\texttt{</xsl:text> + <xsl:apply-templates /> + <xsl:text>}</xsl:text> + </xsl:template> + + <xsl:template match="literal | filename"> + <xsl:text>\texttt{</xsl:text> + <xsl:apply-templates /> + <xsl:text>}</xsl:text> + </xsl:template> + + <xsl:template match="citetitle"> + <xsl:text>\textit{</xsl:text> + <xsl:apply-templates /> + <xsl:text>}</xsl:text> + </xsl:template> + + <xsl:template match="lineannotation"> + <xsl:text>\textit{</xsl:text> + <xsl:apply-templates /> + <xsl:text>}</xsl:text> + </xsl:template> + + <xsl:template match="ulink[@url!='' and not(text())]"> + <xsl:text>\url{</xsl:text> + <xsl:value-of select="@url"/> + <xsl:text>}</xsl:text> + </xsl:template> + + <xsl:template match="ulink[@url!='' and text()]"> + <xsl:text>\href{</xsl:text> + <xsl:value-of select="@url"/> + <xsl:text>}{</xsl:text> + <xsl:apply-templates /> + <xsl:text>}</xsl:text> + </xsl:template> + + <xsl:template match="ulink[(@url='' or not(@url)) and text()]"> + <xsl:text>\url{</xsl:text> + <xsl:apply-templates /> + <xsl:text>}</xsl:text> + </xsl:template> + + <xsl:template match="xref"> + <xsl:choose> + <xsl:when test="@endterm"> + <xsl:value-of select="concat('\hyperref[', @linkend, ']{\mbox{', @endterm, '}}')" /> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="concat($g_nlsChapter, ' \ref{', @linkend, '}, \textit{\nameref{', @linkend, '}}, ', $g_nlsPage, ' \pageref{', @linkend, '}')" /> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <xsl:template match="link"> + <xsl:choose> + <xsl:when test="@endterm"> + <xsl:value-of select="concat('\hyperref[', @linkend, ']{\mbox{', @endterm, '}}')" /> + </xsl:when> + <xsl:when test="./text()"> + <xsl:value-of select="concat('\hyperref[', @linkend, ']{\mbox{')" /> + <xsl:apply-templates select="./text()"/> + <xsl:value-of select="'}}'" /> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="concat($g_nlsChapter, ' \ref{', @linkend, '}, \textit{\nameref{', @linkend, '}}, ', $g_nlsPage, ' \pageref{', @linkend, '}')" /> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <xsl:template match="trademark"> + <xsl:apply-templates /> + <xsl:text>\textsuperscript{\textregistered}</xsl:text> + </xsl:template> + + <!-- for some reason, DocBook insists of having image data nested this way always: + mediaobject -> imageobject -> imagedata + but only imagedata is interesting --> + <xsl:template match="imagedata"> + <xsl:if test="@align='center'"> + <xsl:text>\begin{center}</xsl:text> + </xsl:if> + <xsl:value-of select="concat('
\includegraphics[width=', @width, ']{', @fileref, '}
')" /> + <xsl:apply-templates /> + <xsl:if test="@align='center'"> + <xsl:text>\end{center}</xsl:text> + </xsl:if> + </xsl:template> + + <!-- + Turn the refsynopsisdiv part of a manpage into a named & indented paragraph. + --> + <xsl:template match="refsynopsisdiv"> + <xsl:if test="name(*[1]) != 'cmdsynopsis'"><xsl:message terminate="yes">Expected refsynopsisdiv to start with cmdsynopsis</xsl:message></xsl:if> + <xsl:if test="title"><xsl:message terminate="yes">No title element supported in refsynopsisdiv</xsl:message></xsl:if> + <xsl:call-template name="xsltprocNewlineOutputHack"/> + <xsl:text>
\subsection*{Synopsis}
</xsl:text> + <xsl:apply-templates /> + </xsl:template> + + <!-- + The refsect1 is used for 'Description' and such. Do same as with refsynopsisdiv + and turn it into a named & indented paragraph. + --> + <xsl:template match="refsect1"> + <xsl:if test="name(*[1]) != 'title' or count(title) != 1"> + <xsl:message terminate="yes">Expected exactly one title as the first refsect1 element (remarks goes after title!).</xsl:message> + </xsl:if> + <xsl:apply-templates/> + </xsl:template> + + <!-- + The refsect2 element will be turned into a subparagraph if it has a title, + however, that didn't work out when it didn't have a title and started with + a cmdsynopsis instead (subcommand docs). So, we're doing some trickery + here (HACK ALERT) for the non-title case to feign a paragraph. + --> + <xsl:template match="refsect2"> + <xsl:if test="name(*[1]) != 'title' or count(title) != 1"> + <xsl:message terminate="yes">Expected exactly one title as the first refsect2 element (remarks goes after title!).</xsl:message> + </xsl:if> + <xsl:apply-templates/> + <xsl:text>
</xsl:text> + </xsl:template> + + + <!-- + Command Synopsis elements. + + We treat each command element inside a cmdsynopsis as the start of + a new paragraph. The DocBook HTML converter does so too, but the + manpage one doesn't. + + sbr and linebreaks made by latex should be indented from the base + command level. This is done by the \hangindent3em\hangafter1 bits. + + We exploit the default paragraph indentation to get each command + indented from the left margin. This, unfortunately, doesn't work + if we're the first paragraph in a (sub*)section. \noindent cannot + counter this due to when latex enforces first paragraph stuff. Since + it's tedious to figure out when we're in the first paragraph and when + not, we just do \noindent\hspace{1em} everywhere. + --> + <xsl:template match="sbr"> + <xsl:if test="not(ancestor::cmdsynopsis)"> + <xsl:message terminate="yes">sbr only supported inside cmdsynopsis (because of hangindent)</xsl:message> + </xsl:if> + <xsl:text>\newline</xsl:text> + </xsl:template> + + <xsl:template match="refentry|refnamediv|refentryinfo|refmeta|refsect3|refsect4|refsect5|synopfragment|synopfragmentref|cmdsynopsis/info"> + <xsl:message terminate="yes"><xsl:value-of select="name()"/> is not supported</xsl:message> + </xsl:template> + + <xsl:template match="cmdsynopsis"> + <xsl:if test="preceding-sibling::cmdsynopsis"> + <xsl:text>%cmdsynopsis</xsl:text> + </xsl:if> + <xsl:text>
</xsl:text> + <xsl:text>\begin{flushleft}</xsl:text> + <xsl:if test="parent::remark[@role='VBoxManage-overview']"> + <!-- Overview fontsize trick --> + <xsl:text>{\footnotesize</xsl:text> + </xsl:if> + <xsl:text>\noindent\hspace{1em}</xsl:text> + <xsl:text>\hangindent3em\hangafter1\texttt{</xsl:text> + <xsl:apply-templates /> + <xsl:text>}</xsl:text> + <xsl:if test="following-sibling::*"> + </xsl:if> + + <!-- For refsect2 subcommand descriptions. --> + <xsl:if test="not(following-sibling::cmdsynopsis) and position() != last()"> + <xsl:text>\linebreak</xsl:text> + </xsl:if> + <!-- Special overview trick for the current VBoxManage command overview. --> + <xsl:if test="parent::remark[@role='VBoxManage-overview']"> + <xsl:text>\par}</xsl:text> + </xsl:if> + <xsl:text>\end{flushleft}</xsl:text> + </xsl:template> + + <xsl:template match="command"> + <xsl:choose> + <xsl:when test="ancestor::cmdsynopsis"> + <!-- Trigger a line break if this isn't the first command in a synopsis --> + <xsl:if test="preceding-sibling::command"> + <xsl:text>}\par%command
</xsl:text> + <xsl:text>\noindent\hspace{1em}</xsl:text> + <xsl:text>\hangindent3em\hangafter1\texttt{</xsl:text> + </xsl:if> + <xsl:apply-templates /> + </xsl:when> + <xsl:otherwise> + <xsl:text>\texttt{</xsl:text> + <xsl:apply-templates /> + <xsl:text>}</xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <xsl:template match="option"> + <xsl:choose> + <xsl:when test="ancestor::cmdsynopsis"> + <xsl:apply-templates /> + </xsl:when> + <xsl:otherwise> + <xsl:text>\texttt{</xsl:text> + <xsl:apply-templates /> + <xsl:text>}</xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <!-- duplicated in docbook-refentry-to-C-help.xsl --> + <xsl:template match="arg|group"> + <!-- separator char if we're not the first child --> + <xsl:if test="position() > 1"> + <xsl:choose> + <xsl:when test="parent::group"><xsl:text>\textrm{</xsl:text><xsl:value-of select="$arg.or.sep.tex"/><xsl:text>}</xsl:text></xsl:when> + <xsl:when test="ancestor-or-self::*/@sepchar"><xsl:value-of select="ancestor-or-self::*/@sepchar"/></xsl:when> + <xsl:otherwise><xsl:text> </xsl:text></xsl:otherwise> + </xsl:choose> + </xsl:if> + + <!-- open wrapping --> + <xsl:choose> + <xsl:when test="not(@choice) or @choice = ''"> <xsl:text>\textrm{</xsl:text><xsl:value-of select="$arg.choice.def.open.str"/><xsl:text>}</xsl:text></xsl:when> + <xsl:when test="@choice = 'opt'"> <xsl:text>\textrm{</xsl:text><xsl:value-of select="$arg.choice.opt.open.str"/><xsl:text>}</xsl:text></xsl:when> + <xsl:when test="@choice = 'req'"> <xsl:text>\textrm{</xsl:text><xsl:value-of select="$arg.choice.req.open.str"/><xsl:text>}</xsl:text></xsl:when> + <xsl:when test="@choice = 'plain'"/> + <xsl:otherwise><xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Invalid arg choice: "<xsl:value-of select="@choice"/>"</xsl:message></xsl:otherwise> + </xsl:choose> + + <xsl:apply-templates /> + + <!-- repeat indication --> + <xsl:choose> + <xsl:when test="@rep = 'norepeat' or not(@rep) or @rep = ''"/> + <xsl:when test="@rep = 'repeat'"> + <!-- add space padding if we're in a repeating group --> + <xsl:if test="self::group"> + <xsl:text> </xsl:text> + </xsl:if> + <xsl:text>\textrm{</xsl:text><xsl:value-of select="$arg.rep.repeat.str.tex"/><xsl:text>}</xsl:text> + </xsl:when> + <xsl:otherwise><xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Invalid rep choice: "<xsl:value-of select="@rep"/>"</xsl:message></xsl:otherwise> + </xsl:choose> + + <!-- close wrapping --> + <xsl:choose> + <xsl:when test="not(@choice) or @choice = ''"> <xsl:text>\textrm{</xsl:text><xsl:value-of select="$arg.choice.def.close.str"/><xsl:text>}</xsl:text></xsl:when> + <xsl:when test="@choice = 'opt'"> <xsl:text>\textrm{</xsl:text><xsl:value-of select="$arg.choice.opt.close.str"/><xsl:text>}</xsl:text></xsl:when> + <xsl:when test="@choice = 'req'"> <xsl:text>\textrm{</xsl:text><xsl:value-of select="$arg.choice.req.close.str"/><xsl:text>}</xsl:text></xsl:when> + </xsl:choose> + + <!-- add space padding if we're the last element in a nested arg --> + <xsl:if test="parent::arg and not(following-sibling)"> + <xsl:text> </xsl:text> + </xsl:if> + </xsl:template> + + <xsl:template match="replaceable"> + <xsl:choose> + <xsl:when test="(not(ancestor::cmdsynopsis) and not(ancestor::option) and not(ancestor::screen)) or ancestor::arg"> + <xsl:text>\texttt{\textit{</xsl:text> + <xsl:apply-templates /> + <xsl:text>}}</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>\textit{<</xsl:text> + <xsl:apply-templates /> + <xsl:text>>}</xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + + <!-- + Generic element text magic. + --> + <xsl:template match="//text()"> + + <!-- Do the translation of \ into \textbackslash{} in two steps, to avoid + running into replacing {} as well which would be very wrong. --> + <xsl:variable name="subst1"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="." /> + <xsl:with-param name="replace" select="'\'" /> + <xsl:with-param name="with" select="'\textbackslash'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="subst2"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst1" /> + <xsl:with-param name="replace" select="'{'" /> + <xsl:with-param name="with" select="'\{'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="subst3"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst2" /> + <xsl:with-param name="replace" select="'}'" /> + <xsl:with-param name="with" select="'\}'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="subst4"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst3" /> + <xsl:with-param name="replace" select="'\textbackslash'" /> + <xsl:with-param name="with" select="'\textbackslash{}'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + + <xsl:choose> + <xsl:when test="(name(..) = 'computeroutput') or (name(../..) = 'computeroutput') + or (name(..) = 'code') or (name(../..) = 'code') + or (name(..) = 'arg') or (name(../..) = 'arg') + or (name(..) = 'option') or (name(../..) = 'option') + or (name(..) = 'command') or (name(../..) = 'command') + or (name(..) = 'cmdsynopsis') or (name(../..) = 'cmdsynopsis') + or (name(..) = 'replaceable') or (name(../..) = 'replaceable') + or (name(..) = 'entry') or (name(../..) = 'entry') + "> + <xsl:variable name="subst5"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="translate(normalize-space(concat('',$subst4,'')),'','')" /> + <xsl:with-param name="replace" select="'--'" /> + <xsl:with-param name="with" select="'-{}-'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="subst6"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst5" /> + <xsl:with-param name="replace" select="'_'" /> + <xsl:with-param name="with" select="'\_'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="subst7"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst6" /> + <xsl:with-param name="replace" select="'$'" /> + <xsl:with-param name="with" select="'\$'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="subst8"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst7" /> + <xsl:with-param name="replace" select="'%'" /> + <xsl:with-param name="with" select="'\%'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="subst9"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst8" /> + <xsl:with-param name="replace" select="'#'" /> + <xsl:with-param name="with" select="'\#'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="subst10"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst9" /> + <xsl:with-param name="replace" select="'~'" /> + <xsl:with-param name="with" select="'\textasciitilde{}'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="subst11"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst10" /> + <xsl:with-param name="replace" select="'&'" /> + <xsl:with-param name="with" select="'\&'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:choose> + <xsl:when test="parent::arg or parent::command"> + <xsl:variable name="subst12"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst10" /> + <xsl:with-param name="replace" select="' '" /> + <xsl:with-param name="with" select="'~'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:value-of select="$subst12" /> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$subst11" /> + </xsl:otherwise> + </xsl:choose> + </xsl:when> + + <xsl:when test="(name(..)='address') or (name(../..)='address')"> + <xsl:variable name="subst5"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst4" /> + <xsl:with-param name="replace" select="'
'" /> + <xsl:with-param name="with" select="' \\'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:value-of select="$subst5" /> + </xsl:when> + + <!-- <screen> and <programlisting>, which work with alltt environment. --> + <xsl:otherwise> + <xsl:variable name="subst5"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst4" /> + <xsl:with-param name="replace" select="'_'" /> + <xsl:with-param name="with" select="'\_'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="subst6"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst5" /> + <xsl:with-param name="replace" select="'$'" /> + <xsl:with-param name="with" select="'\$'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="subst7"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst6" /> + <xsl:with-param name="replace" select="'%'" /> + <xsl:with-param name="with" select="'\%'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="subst8"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst7" /> + <xsl:with-param name="replace" select="'#'" /> + <xsl:with-param name="with" select="'\#'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="subst9"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst8" /> + <xsl:with-param name="replace" select="'µ'" /> + <xsl:with-param name="with" select="'$\mu$'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="subst10"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst9" /> + <xsl:with-param name="replace" select="'®'" /> + <xsl:with-param name="with" select="'\texorpdfstring{\textregistered}{}'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="quote">"</xsl:variable> + <!-- preparation for pretty quotes: replace all double quotes _outside_ screen + sections with "\QUOTE{}" strings, which the makefile will then replace + with pretty quotes by invoking sed a few times. Unfortunately there are + no regular expressions in XSLT so there's no other way. --> + <xsl:variable name="subst11"> + <xsl:choose> + <xsl:when test="(name(..)='screen') or (name(../..)='screen') + or (name(..)='programlisting') or (name(../..)='programlisting') + or (name(..)='literal') or (name(../..)='literal') + "> + <xsl:value-of select="$subst10" /> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst10" /> + <xsl:with-param name="replace" select="$quote" /> + <xsl:with-param name="with" select="'\QUOTE{}'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:variable name="subst12"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst11" /> + <xsl:with-param name="replace" select="'~'" /> + <xsl:with-param name="with" select="'\textasciitilde{}'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="subst13"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst12" /> + <xsl:with-param name="replace" select="'&'" /> + <xsl:with-param name="with" select="'\&'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="subst14"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst13" /> + <xsl:with-param name="replace" select="'→'" /> + <xsl:with-param name="with" select="'\ensuremath{\rightarrow}'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="subst15"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst14" /> + <xsl:with-param name="replace" select="'←'" /> + <xsl:with-param name="with" select="'\ensuremath{\leftarrow}'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="subst16"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$subst15" /> + <xsl:with-param name="replace" select="'↔'" /> + <xsl:with-param name="with" select="'\ensuremath{\leftrightarrow}'" /> + <xsl:with-param name="disable-output-escaping" select="no" /> + </xsl:call-template> + </xsl:variable> + <xsl:value-of select="$subst16" /> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <!-- + xsltprocNewlineOutputHack - emits a single new line. + + Hack Alert! This template helps xsltproc split up the output text elements + and avoid reallocating them into the MB range. Calls to this + template is made occationally while generating larger output + file. It's not necessary for small stuff like header. + + The trick we're playing on xsltproc has to do with CDATA + and/or the escape setting of the xsl:text element. It forces + xsltproc to allocate a new output element, thus preventing + things from growing out of proportions and slowing us down. + + This was successfully employed to reduce a 18+ seconds run to + around one second (possibly less due to kmk overhead). + --> + <xsl:template name="xsltprocNewlineOutputHack"> + <xsl:text disable-output-escaping="yes"><![CDATA[ +]]></xsl:text> + </xsl:template> + +</xsl:stylesheet> + diff --git a/doc/manual/dummy-sect1.xml b/doc/manual/dummy-sect1.xml new file mode 100644 index 00000000..8e62181b --- /dev/null +++ b/doc/manual/dummy-sect1.xml @@ -0,0 +1,29 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2019-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<sect1> + Blah. + <xsect2> + More blah. + </xsect2> +</sect1> + diff --git a/doc/manual/en_US/.scm-settings b/doc/manual/en_US/.scm-settings new file mode 100644 index 00000000..0620353d --- /dev/null +++ b/doc/manual/en_US/.scm-settings @@ -0,0 +1,32 @@ +# $Id: .scm-settings $ +## @file +# Source code massager settings for the manual. +# + +# +# Copyright (C) 2010-2023 Oracle and/or its affiliates. +# +# This file is part of VirtualBox base platform packages, as +# available from https://www.virtualbox.org. +# +# 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, in version 3 of the +# License. +# +# 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, see <https://www.gnu.org/licenses>. +# +# SPDX-License-Identifier: GPL-3.0-only +# + + +/oracle-accessibility-ohc-en.xml: --external-copyright --no-strip-trailing-blanks +/oracle-support-en.xml: --external-copyright --no-strip-trailing-blanks +/oracle-diversity.xml: --external-copyright --no-strip-trailing-blanks + diff --git a/doc/manual/en_US/Accessibility.xml b/doc/manual/en_US/Accessibility.xml new file mode 100644 index 00000000..149a0090 --- /dev/null +++ b/doc/manual/en_US/Accessibility.xml @@ -0,0 +1,250 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> + +<book> + <bookinfo> + <title>&VBOX_PRODUCT;</title> + + <subtitle>Accessibility Reference</subtitle> + + <edition>Version &VBOX_VERSION_STRING;</edition> + + <corpauthor>&VBOX_VENDOR;</corpauthor> + + <address>https://www.virtualbox.org</address> + + <copyright> + <year>2016-&VBOX_C_YEAR;</year> + + <holder>&VBOX_VENDOR;</holder> + </copyright> + </bookinfo> + + <chapter> + <title>Introduction</title> + <para> + Welcome to the <emphasis role="bold">VirtualBox Accessibility Support</emphasis> documentation! This document is primarily + a reference to help people who are interested in our project accessibility support and will describe how to use VirtualBox + user interface step-by-step. Since whole the application navigation will be explained here, this document will also be + helpful for those who are not familiar with our product user interface and wish to learn more. It will be written in a bit + excessive manner so that many obvious things will be explained too precisely to make it easier to understand by ear for a + blind users. The document will be periodically updated with recent changes and test-cases allowing us to more strictly + follow the required guidelines and make our product fully accessible. + </para> + <para> + Our application is based on Qt5, a powerful cross-platform library which allows to visualize various user interface ideas + the most flexible and native way. This also means that the library we use is responsible for many navigation and + accessibility aspects (like fonts, size hints, colors, look&feel patterns and many other things), but not for all of + them. Nativity as one of the main ideas of the Qt-based application sometimes brings additional complexity because there is + always at least one host which uses unique combination of fonts and colors which breaks accessibility support in an + unpredictable way. + </para> + <para> + Independently on platform we are supporting screen-reader applications which can communicate with Qt5 accessibility + interface which supports Microsoft Active Accessibility (MSAA), OS X Accessibility, and the Unix/X11 AT-SPI standard. + </para> + <para> + Our application user interface is able to be started in two modes: + <itemizedlist> + <listitem> + <para> + First of them is <emphasis role="bold">VirtualBox Manager</emphasis> user interface, the main application window + which allows to manage and configure virtual machines and their groups. Besides that, this window provides user with + access to various global and machine related tools allowing to administrate some of VirtualBox objects and their + settings. + </para> + </listitem> + <listitem> + <para> + Second application mode is <emphasis role="bold">Virtual Machine</emphasis> user interface, which allows to control + virtual machine guest screens as separate application windows. Besides that, this interface allows to access some of + machine tools and adjust guest screens up to your needs, by changing their resolution and toggling full-screen, + seamless and scaled modes. + </para> + </listitem> + </itemizedlist> + But first of all we should start from the <emphasis role="bold">General Concept</emphasis> which is related to whole the + GUI and summarizes the navigation and accessibility aspects we are using for whole application. + </para> + </chapter> + + <chapter> + <title>General concept</title> + <para> + This chapter describes the general navigation and accessibility concept. We should note that not every detail of this + concept is already implemented and not every widget in our project already follows that concept. There is still large work + to be done in that regard. But in the end whole the project should correspond to this concept. + </para> + <para> + In short, every application window of our project should be navigated using the following approaches: + <itemizedlist> + <listitem><para>Mouse Navigation</para></listitem> + <listitem><para>Keyboard Navigation</para></listitem> + <listitem><para>Screen-reader Navigation</para></listitem> + </itemizedlist> + </para> + <sect1> + <title>Mouse Navigation</title> + <itemizedlist> + <listitem> + <para> + Each interactable widget can be focused with mouse (if that is not restricted by underlying host OS). + </para> + </listitem> + <listitem> + <para> + Each hovered interactable widget causes own tool-tip to appear. + </para> + </listitem> + <listitem> + <para> + Each tool-tip is given either in imperative mood (ex. "Create new virtual machine") or in short form (ex. "New"). + </para> + </listitem> + <listitem> + <para> + Short tool-tip form is only used if context is obvious for a user. + </para> + </listitem> + <listitem> + <para> + Tool-tip can contain shortcut mentioned in parentheses. + </para> + </listitem> + <listitem> + <para> + Each hovered menu bar / toolbar action causes own status-tip to appear (if window have status-bar). + </para> + </listitem> + <listitem> + <para> + Each status-tip is given in imperative mood only. + </para> + </listitem> + <listitem> + <para> + TBD... + </para> + </listitem> + </itemizedlist> + </sect1> + <sect1> + <title>Keyboard Navigation</title> + <itemizedlist> + <listitem> + <para> + Each interactable widget can be focused with keyboard (if that is not restricted by underlying host OS). + </para> + </listitem> + <listitem> + <para> + Focusing is possible through tabbing or mnemonic navigation. + </para> + </listitem> + <listitem> + <para> + Each button and menu bar / toolbar action can be directly activated with keyboard. + </para> + </listitem> + <listitem> + <para> + Activation is possible via shortcut or mnemonic. + </para> + </listitem> + <listitem> + <para> + Each shortcut is configurable through application preferences. + </para> + </listitem> + <listitem> + <para> + Mnemonic mentioned above is underlined alphanumeric character which is a part of widget label (if widget has label). + Mnemonic being triggered in conjunction with the Alt key. + </para> + </listitem> + <listitem> + <para> + Each mnemonic is unique within the visible part of current application window, there are no collisions. + </para> + </listitem> + <listitem> + <para> + TBD... + </para> + </listitem> + </itemizedlist> + </sect1> + <sect1> + <title>Screen-reader Navigation</title> + <itemizedlist> + <listitem> + <para> + Each interactable widget can be focused with screen-reader cursor. + </para> + </listitem> + <listitem> + <para> + Each focused widget have clear name (or full description) in native user language. + </para> + </listitem> + <listitem> + <para> + Each button and menu bar / toolbar action can be directly activated through the screen-reader cursor functionality. + </para> + </listitem> + <listitem> + <para> + Each complex widget which has children (like list, tree, table and similar) is represented as closed group which + encapsulates it's children clearly. + </para> + </listitem> + <listitem> + <para> + While navigating user is able to skip any group without forcing to be entered inside. + </para> + </listitem> + <listitem> + <para> + Each group child can be a group itself with the same rules as above applicable. + </para> + </listitem> + <listitem> + <para> + Each text-field can be directly edited through the screen-reader cursor functionality. + </para> + </listitem> + <listitem> + <para> + TBD... + </para> + </listitem> + </itemizedlist> + </sect1> + </chapter> +</book> +<!-- vim: set shiftwidth=2 tabstop=2 expandtab: --> diff --git a/doc/manual/en_US/Makefile.kup b/doc/manual/en_US/Makefile.kup new file mode 100644 index 00000000..e69de29b --- /dev/null +++ b/doc/manual/en_US/Makefile.kup diff --git a/doc/manual/en_US/SDKRef.xml b/doc/manual/en_US/SDKRef.xml new file mode 100644 index 00000000..307d13f6 --- /dev/null +++ b/doc/manual/en_US/SDKRef.xml @@ -0,0 +1,6324 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> + +<book> + <bookinfo> + <title>&VBOX_PRODUCT;</title> + + <subtitle>Programming Guide and Reference</subtitle> + + <edition>Version &VBOX_VERSION_STRING;</edition> + + <corpauthor>&VBOX_VENDOR;</corpauthor> + + <address>http://www.virtualbox.org</address> + + <copyright> + <year>2004-&VBOX_C_YEAR;</year> + + <holder>&VBOX_VENDOR;</holder> + </copyright> + </bookinfo> + + <chapter> + <title>Introduction</title> + + <para>VirtualBox comes with comprehensive support for third-party + developers. This Software Development Kit (SDK) contains all the + documentation and interface files that are needed to write code that + interacts with VirtualBox.</para> + + <sect1> + <title>Modularity: the building blocks of VirtualBox</title> + + <para>VirtualBox is cleanly separated into several layers, which can be + visualized like in the picture below:</para> + + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/vbox-components.png" + width="12cm"/> + </imageobject> + </mediaobject> + + <para>The orange area represents code that runs in kernel mode, the blue + area represents userspace code.</para> + + <para>At the bottom of the stack resides the hypervisor -- the core of + the virtualization engine, controlling execution of the virtual machines + and making sure they do not conflict with each other or whatever the + host computer is doing otherwise.</para> + + <para>On top of the hypervisor, additional internal modules provide + extra functionality. For example, the RDP server, which can deliver the + graphical output of a VM remotely to an RDP client, is a separate module + that is only loosely tacked into the virtual graphics device. Live + Migration and Resource Monitor are additional modules currently in the + process of being added to VirtualBox.</para> + + <para>What is primarily of interest for purposes of the SDK is the API + layer block that sits on top of all the previously mentioned blocks. + This API, which we call the <emphasis role="bold">"Main API"</emphasis>, + exposes the entire feature set of the virtualization engine below. It is + completely documented in this SDK Reference -- see <xref + linkend="sdkref_classes"/> and <xref linkend="sdkref_enums"/> -- and + available to anyone who wishes to control VirtualBox programmatically. + We chose the name "Main API" to differentiate it from other programming + interfaces of VirtualBox that may be publicly accessible.</para> + + <para>With the Main API, you can create, configure, start, stop and + delete virtual machines, retrieve performance statistics about running + VMs, configure the VirtualBox installation in general, and more. In + fact, internally, the front-end programs + <computeroutput>VirtualBox</computeroutput> and + <computeroutput>VBoxManage</computeroutput> use nothing but this API as + well -- there are no hidden backdoors into the virtualization engine for + our own front-ends. This ensures the entire Main API is both + well-documented and well-tested. (The same applies to + <computeroutput>VBoxHeadless</computeroutput>, which is not shown in the + image.)</para> + </sect1> + + <sect1 id="webservice-or-com"> + <title>Two guises of the same "Main API": the web service or + COM/XPCOM</title> + + <para>There are several ways in which the Main API can be called by + other code:<orderedlist> + <listitem> + <para>VirtualBox comes with a <emphasis role="bold">web + service</emphasis> that maps nearly the entire Main API. The web + service ships in a stand-alone executable + (<computeroutput>vboxwebsrv</computeroutput>) that, when running, + acts as an HTTP server, accepts SOAP connections and processes + them.</para> + + <para>Since the entire web service API is publicly described in a + web service description file (in WSDL format), you can write + client programs that call the web service in any language with a + toolkit that understands WSDL. These days, that includes most + programming languages that are available: Java, C++, .NET, PHP, + Python, Perl and probably many more.</para> + + <para>All of this is explained in detail in subsequent chapters of + this book.</para> + + <para>There are two ways in which you can write client code that + uses the web service:<orderedlist> + <listitem> + <para>For Java as well as Python, the SDK contains + easy-to-use classes that allow you to use the web service in + an object-oriented, straightforward manner. We shall refer + to this as the <emphasis role="bold">"object-oriented web + service (OOWS)"</emphasis>.</para> + + <para>The OO bindings for Java are described in <xref + linkend="javaapi"/>, those for Python in <xref + linkend="glue-python-ws"/>.</para> + </listitem> + + <listitem> + <para>Alternatively, you can use the web service directly, + without the object-oriented client layer. We shall refer to + this as the <emphasis role="bold">"raw web + service"</emphasis>.</para> + + <para>You will then have neither native object orientation + nor full type safety, since web services are neither + object-oriented nor stateful. However, in this way, you can + write client code even in languages for which we do not ship + object-oriented client code; all you need is a programming + language with a toolkit that can parse WSDL and generate + client wrapper code from it.</para> + + <para>We describe this further in <xref + linkend="raw-webservice"/>, with samples for Java and + Perl.</para> + </listitem> + </orderedlist></para> + </listitem> + + <listitem> + <para>Internally, for portability and easier maintenance, the Main + API is implemented using the <emphasis role="bold">Component + Object Model (COM), </emphasis> an interprocess mechanism for + software components originally introduced by Microsoft for + Microsoft Windows. On a Windows host, VirtualBox will use + Microsoft COM; on other hosts where COM is not present, it ships + with XPCOM, a free software implementation of COM originally + created by the Mozilla project for their browsers.</para> + + <para>So, if you are familiar with COM and the C++ programming + language (or with any other programming language that can handle + COM/XPCOM objects, such as Java, Visual Basic or C#), then you can + use the COM/XPCOM API directly. VirtualBox comes with all + necessary files and documentation to build fully functional COM + applications. For an introduction, please see <xref + linkend="api_com"/> below.</para> + + <para>The VirtualBox front-ends (the graphical user interfaces as + well as the command line), which are all written in C++, use + COM/XPCOM to call the Main API. Technically, the web service is + another front-end to this COM API, mapping almost all of it to + SOAP clients.</para> + </listitem> + </orderedlist></para> + + <para>If you wonder which way to choose, here are a few + comparisons:<table> + <title>Comparison web service vs. COM/XPCOM</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry><emphasis role="bold">Web service</emphasis></entry> + + <entry><emphasis role="bold">COM/XPCOM</emphasis></entry> + </row> + + <row> + <entry><emphasis role="bold">Pro:</emphasis> Easy to use with + Java and Python with the object-oriented web service; + extensive support even with other languages (C++, .NET, PHP, + Perl and others)</entry> + + <entry><emphasis role="bold">Con:</emphasis> Usable from + languages where COM bridge available (most languages on + Windows platform, Python and C++ on other hosts)</entry> + </row> + + <row> + <entry><emphasis role="bold">Pro:</emphasis> Client can be on + remote machine</entry> + + <entry><emphasis role="bold">Con: </emphasis>Client must be on + the same host where virtual machine is executed</entry> + </row> + + <row> + <entry><emphasis role="bold">Con: </emphasis>Significant + overhead due to XML marshalling over the wire for each method + call</entry> + + <entry><emphasis role="bold">Pro: </emphasis>Relatively low + invocation overhead</entry> + </row> + </tbody> + </tgroup> + </table></para> + + <para>In the following chapters, we will describe the different ways in + which to program VirtualBox, starting with the method that is easiest to + use and then increase complexity as we go along.</para> + </sect1> + + <sect1 id="api_soap_intro"> + <title>About web services in general</title> + + <para>Web services are a particular type of programming interface. + Whereas, with "normal" programming, a program calls an application + programming interface (API) defined by another program or the operating + system and both sides of the interface have to agree on the calling + convention and, in most cases, use the same programming language, web + services use Internet standards such as HTTP and XML to + communicate.<footnote> + <para>In some ways, web services promise to deliver the same thing + as CORBA and DCOM did years ago. However, while these previous + technologies relied on specific binary protocols and thus proved to + be difficult to use between diverging platforms, web services + circumvent these incompatibilities by using text-only standards like + HTTP and XML. On the downside (and, one could say, typical of things + related to XML), a lot of standards are involved before a web + service can be implemented. Many of the standards invented around + XML are used one way or another. As a result, web services are slow + and verbose, and the details can be incredibly messy. The relevant + standards here are called SOAP and WSDL, where SOAP describes the + format of the messages that are exchanged (an XML document wrapped + in an HTTP header), and WSDL is an XML format that describes a + complete API provided by a web service. WSDL in turn uses XML Schema + to describe types, which is not exactly terse either. However, as + you will see from the samples provided in this chapter, the + VirtualBox web service shields you from these details and is easy to + use.</para> + </footnote></para> + + <para>In order to successfully use a web service, a number of things are + required -- primarily, a web service accepting connections; service + descriptions; and then a client that connects to that web service. The + connections are governed by the SOAP standard, which describes how + messages are to be exchanged between a service and its clients; the + service descriptions are governed by WSDL.</para> + + <para>In the case of VirtualBox, this translates into the following + three components:<orderedlist> + <listitem> + <para>The VirtualBox web service (the "server"): this is the + <computeroutput>vboxwebsrv</computeroutput> executable shipped + with VirtualBox. Once you start this executable (which acts as a + HTTP server on a specific TCP/IP port), clients can connect to the + web service and thus control a VirtualBox installation.</para> + </listitem> + + <listitem> + <para>VirtualBox also comes with WSDL files that describe the + services provided by the web service. You can find these files in + the <computeroutput>sdk/bindings/webservice/</computeroutput> + directory. These files are understood by the web service toolkits + that are shipped with most programming languages and enable you to + easily access a web service even if you don't use our + object-oriented client layers. VirtualBox is shipped with + pregenerated web service glue code for several languages (Python, + Perl, Java).</para> + </listitem> + + <listitem> + <para>A client that connects to the web service in order to + control the VirtualBox installation.</para> + + <para>Unless you play with some of the samples shipped with + VirtualBox, this needs to be written by you.</para> + </listitem> + </orderedlist></para> + </sect1> + + <sect1 id="runvboxwebsrv"> + <title>Running the web service</title> + + <para>The web service ships in an stand-alone executable, + <computeroutput>vboxwebsrv</computeroutput>, that, when running, acts as + a HTTP server, accepts SOAP connections and processes them -- remotely + or from the same machine.<note> + <para>The web service executable is not contained with the + VirtualBox SDK, but instead ships with the standard VirtualBox + binary package for your specific platform. Since the SDK contains + only platform-independent text files and documentation, the binaries + are instead shipped with the platform-specific packages. For this + reason the information how to run it as a service is included in the + VirtualBox documentation.</para> + </note></para> + + <para>The <computeroutput>vboxwebsrv</computeroutput> program, which + implements the web service, is a text-mode (console) program which, + after being started, simply runs until it is interrupted with Ctrl-C or + a kill command.</para> + + <para>Once the web service is started, it acts as a front-end to the + VirtualBox installation of the user account that it is running under. In + other words, if the web service is run under the user account of + <computeroutput>user1</computeroutput>, it will see and manipulate the + virtual machines and other data represented by the VirtualBox data of + that user (for example, on a Linux machine, under + <computeroutput>/home/user1/.config/VirtualBox</computeroutput>; see the + VirtualBox User Manual for details on where this data is stored).</para> + + <sect2 id="vboxwebsrv-ref"> + <title>Command line options of vboxwebsrv</title> + + <para>The web service supports the following command line + options:</para> + + <itemizedlist> + <listitem> + <para><computeroutput>--help</computeroutput> (or + <computeroutput>-h</computeroutput>): print a brief summary of + command line options.</para> + </listitem> + + <listitem> + <para><computeroutput>--background</computeroutput> (or + <computeroutput>-b</computeroutput>): run the web service as a + background daemon. This option is not supported on Windows + hosts.</para> + </listitem> + + <listitem> + <para><computeroutput>--host</computeroutput> (or + <computeroutput>-H</computeroutput>): This specifies the host to + bind to and defaults to "localhost".</para> + </listitem> + + <listitem> + <para><computeroutput>--port</computeroutput> (or + <computeroutput>-p</computeroutput>): This specifies which port to + bind to on the host and defaults to 18083.</para> + </listitem> + + <listitem> + <para><computeroutput>--ssl</computeroutput> (or + <computeroutput>-s</computeroutput>): This enables SSL + support.</para> + </listitem> + + <listitem> + <para><computeroutput>--keyfile</computeroutput> (or + <computeroutput>-K</computeroutput>): This specifies the file name + containing the server private key and the certificate. This is a + mandatory parameter if SSL is enabled.</para> + </listitem> + + <listitem> + <para><computeroutput>--passwordfile</computeroutput> (or + <computeroutput>-a</computeroutput>): This specifies the file name + containing the password for the server private key. If unspecified + or an empty string is specified this is interpreted as an empty + password (i.e. the private key is not protected by a password). If + the file name <computeroutput>-</computeroutput> is specified then + then the password is read from the standard input stream, otherwise + from the specified file. The user is responsible for appropriate + access rights to protect the confidential password.</para> + </listitem> + + <listitem> + <para><computeroutput>--cacert</computeroutput> (or + <computeroutput>-c</computeroutput>): This specifies the file name + containing the CA certificate appropriate for the server + certificate.</para> + </listitem> + + <listitem> + <para><computeroutput>--capath</computeroutput> (or + <computeroutput>-C</computeroutput>): This specifies the directory + containing several CA certificates appropriate for the server + certificate.</para> + </listitem> + + <listitem> + <para><computeroutput>--dhfile</computeroutput> (or + <computeroutput>-D</computeroutput>): This specifies the file name + containing the DH key. Alternatively it can contain the number of + bits of the DH key to generate. If left empty, RSA is used.</para> + </listitem> + + <listitem> + <para><computeroutput>--randfile</computeroutput> (or + <computeroutput>-r</computeroutput>): This specifies the file name + containing the seed for the random number generator. If left empty, + an operating system specific source of the seed.</para> + </listitem> + + <listitem> + <para><computeroutput>--timeout</computeroutput> (or + <computeroutput>-t</computeroutput>): This specifies the session + timeout, in seconds, and defaults to 300 (five minutes). A web + service client that has logged on but makes no calls to the web + service will automatically be disconnected after the number of + seconds specified here, as if it had called the + <computeroutput>IWebSessionManager::logoff()</computeroutput> + method provided by the web service itself.</para> + + <para>It is normally vital that each web service client call this + method, as the web service can accumulate large amounts of memory + when running, especially if a web service client does not properly + release managed object references. As a result, this timeout value + should not be set too high, especially on machines with a high + load on the web service, or the web service may eventually deny + service.</para> + </listitem> + + <listitem> + <para><computeroutput>--check-interval</computeroutput> (or + <computeroutput>-i</computeroutput>): This specifies the interval + in which the web service checks for timed-out clients, in seconds, + and defaults to 5. This normally does not need to be + changed.</para> + </listitem> + + <listitem> + <para><computeroutput>--threads</computeroutput> (or + <computeroutput>-T</computeroutput>): This specifies the maximum + number or worker threads, and defaults to 100. This normally does + not need to be changed.</para> + </listitem> + + <listitem> + <para><computeroutput>--keepalive</computeroutput> (or + <computeroutput>-k</computeroutput>): This specifies the maximum + number of requests which can be sent in one web service connection, + and defaults to 100. This normally does not need to be + changed.</para> + </listitem> + + <listitem> + <para><computeroutput>--authentication</computeroutput> (or + <computeroutput>-A</computeroutput>): This specifies the desired + web service authentication method. If the parameter is not + specified or the empty string is specified it does not change the + authentication method, otherwise it is set to the specified value. + Using this parameter is a good measure against accidental + misconfiguration, as the web service ensures periodically that it + isn't changed.</para> + </listitem> + + <listitem> + <para><computeroutput>--verbose</computeroutput> (or + <computeroutput>-v</computeroutput>): Normally, the web service + outputs only brief messages to the console each time a request is + served. With this option, the web service prints much more detailed + data about every request and the COM methods that those requests + are mapped to internally, which can be useful for debugging client + programs.</para> + </listitem> + + <listitem> + <para><computeroutput>--pidfile</computeroutput> (or + <computeroutput>-P</computeroutput>): Name of the PID file which is + created when the daemon was started.</para> + </listitem> + + <listitem> + <para><computeroutput>--logfile</computeroutput> (or + <computeroutput>-F</computeroutput>) + <computeroutput><file></computeroutput>: If this is + specified, the web service not only prints its output to the + console, but also writes it to the specified file. The file is + created if it does not exist; if it does exist, new output is + appended to it. This is useful if you run the web service + unattended and need to debug problems after they have + occurred.</para> + </listitem> + + <listitem> + <para><computeroutput>--logrotate</computeroutput> (or + <computeroutput>-R</computeroutput>): Number of old log files to + keep, defaults to 10. Log rotation is disabled if set to 0.</para> + </listitem> + + <listitem> + <para><computeroutput>--logsize</computeroutput> (or + <computeroutput>-S</computeroutput>): Maximum size of log file in + bytes, defaults to 100MB. Log rotation is triggered if the file + grows beyond this limit.</para> + </listitem> + + <listitem> + <para><computeroutput>--loginterval</computeroutput> (or + <computeroutput>-I</computeroutput>): Maximum time interval to be + put in a log file before rotation is triggered, in seconds, and + defaults to one day.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2 id="websrv_authenticate"> + <title>Authenticating at web service logon</title> + + <para>As opposed to the COM/XPCOM variant of the Main API, a client + that wants to use the web service must first log on by calling the + <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link> + API that is specific to the + web service. Logon is necessary for the web service to be stateful; + internally, it maintains a session for each client that connects to + it.</para> + + <para>The <computeroutput>IWebsessionManager::logon()</computeroutput> + API takes a user name and a password as arguments, which the web + service then passes to a customizable authentication plugin that + performs the actual authentication.</para> + + <para>For testing purposes, it is recommended that you first disable + authentication with this command: + <screen>VBoxManage setproperty websrvauthlibrary null</screen></para> + + <para><warning> + <para>This will cause all logons to succeed, regardless of user + name or password. This should of course not be used in a + production environment.</para> + </warning>Generally, the mechanism by which clients are + authenticated is configurable by way of the + <computeroutput>VBoxManage</computeroutput> command:</para> + + <para><screen>VBoxManage setproperty websrvauthlibrary default|null|<library></screen></para> + + <para>This way you can specify any shared object/dynamic link module + that conforms with the specifications for VirtualBox external + authentication modules as laid out in section <emphasis + role="bold">VRDE authentication</emphasis> of the VirtualBox User + Manual; the web service uses the same kind of modules as the + VirtualBox VRDE server. For technical details on VirtualBox external + authentication modules see <xref linkend="vbox-auth"/></para> + + <para>By default, after installation, the web service uses the + VBoxAuth module that ships with VirtualBox. This module uses PAM on + Linux hosts to authenticate users. Any valid username/password + combination is accepted, it does not have to be the username and + password of the user running the web service daemon. Unless + <computeroutput>vboxwebsrv</computeroutput> runs as root, PAM + authentication can fail, because sometimes the file + <computeroutput>/etc/shadow</computeroutput>, which is used by PAM, is + not readable. On most Linux distribution PAM uses a suid root helper + internally, so make sure you test this before deploying it. One can + override this behavior by setting the environment variable + <computeroutput>VBOX_PAM_ALLOW_INACTIVE</computeroutput> which will + suppress failures when unable to read the shadow password file. Please + use this variable carefully, and only if you fully understand what + you're doing.</para> + </sect2> + </sect1> + </chapter> + + <chapter> + <title>Environment-specific notes</title> + + <para>The Main API described in <xref linkend="sdkref_classes"/> and + <xref linkend="sdkref_enums"/> is mostly identical in all the supported + programming environments which have been briefly mentioned in the + introduction of this book. As a result, the Main API's general concepts + described in <xref linkend="concepts"/> are the same whether you use the + object-oriented web service (OOWS) for JAX-WS or a raw web service + connection via, say, Perl, or whether you use C++ COM bindings.</para> + + <para>Some things are different depending on your environment, however. + These differences are explained in this chapter.</para> + + <sect1 id="glue"> + <title>Using the object-oriented web service (OOWS)</title> + + <para>As explained in <xref linkend="webservice-or-com"/>, VirtualBox + ships with client-side libraries for Java, Python and PHP that allow you + to use the VirtualBox web service in an intuitive, object-oriented way. + These libraries shield you from the client-side complications of managed + object references and other implementation details that come with the + VirtualBox web service. (If you are interested in these complications, + have a look at <xref linkend="raw-webservice"/>).</para> + + <para>We recommend that you start your experiments with the VirtualBox + web service by using our object-oriented client libraries for JAX-WS, a + web service toolkit for Java, which enables you to write code to + interact with VirtualBox in the simplest manner possible.</para> + + <para>As "interfaces", "attributes" and "methods" are COM concepts, + please read the documentation in <xref linkend="sdkref_classes"/> and + <xref linkend="sdkref_enums"/> with the following notes in mind.</para> + + <para>The OOWS bindings attempt to map the Main API as closely as + possible to the Java, Python and PHP languages. In other words, objects + are objects, interfaces become classes, and you can call methods on + objects as you would on local objects.</para> + + <para>The main difference remains with attributes: to read an attribute, + call a "getXXX" method, with "XXX" being the attribute name with a + capitalized first letter. So when the Main API Reference says that + <computeroutput>IMachine</computeroutput> has a "name" attribute (see + <link linkend="IMachine__name">IMachine::name</link>), call + <computeroutput>getName()</computeroutput> on an IMachine object to + obtain a machine's name. Unless the attribute is marked as read-only in + the documentation, there will also be a corresponding "set" + method.</para> + + <sect2 id="glue-jax-ws"> + <title>The object-oriented web service for JAX-WS</title> + + <para>JAX-WS is a powerful toolkit by Sun Microsystems to build both + server and client code with Java. It is part of Java 6 (JDK 1.6), but + can also be obtained separately for Java 5 (JDK 1.5). The VirtualBox + SDK comes with precompiled OOWS bindings working with both Java 5 and + 6.</para> + + <para>The following sections explain how to get the JAX-WS sample code + running and explain a few common practices when using the JAX-WS + object-oriented web service.</para> + + <sect3> + <title>Preparations</title> + + <para>Since JAX-WS is already integrated into Java 6, no additional + preparations are needed for Java 6.</para> + + <para>If you are using Java 5 (JDK 1.5.x), you will first need to + download and install an external JAX-WS implementation, as Java 5 + does not support JAX-WS out of the box; for example, you can + download one from here: <ulink + url="https://jax-ws.dev.java.net/2.1.4/JAXWS2.1.4-20080502.jar">https://jax-ws.dev.java.net/2.1.4/JAXWS2.1.4-20080502.jar</ulink>. + Then perform the installation (<computeroutput>java -jar + JAXWS2.1.4-20080502.jar</computeroutput>).</para> + </sect3> + + <sect3> + <title>Getting started: running the sample code</title> + + <para>To run the OOWS for JAX-WS samples that we ship with the SDK, + perform the following steps: <orderedlist> + <listitem> + <para>Open a terminal and change to the directory where the + JAX-WS samples reside.<footnote> + <para>In + <computeroutput>sdk/bindings/glue/java/</computeroutput>.</para> + </footnote> Examine the header of + <computeroutput>Makefile</computeroutput> to see if the + supplied variables (Java compiler, Java executable) and a few + other details match your system settings.</para> + </listitem> + + <listitem> + <para>To start the VirtualBox web service, open a second + terminal and change to the directory where the VirtualBox + executables are located. Then type: + <screen>./vboxwebsrv -v</screen></para> + + <para>The web service now waits for connections and will run + until you press Ctrl+C in this second terminal. The -v + argument causes it to log all connections to the terminal. + (See <xref linkend="runvboxwebsrv"/> for details on how + to run the web service.)</para> + </listitem> + + <listitem> + <para>Back in the first terminal and still in the samples + directory, to start a simple client example just type: + <screen>make run16</screen></para> + + <para>if you're on a Java 6 system; on a Java 5 system, run + <computeroutput>make run15</computeroutput> instead.</para> + + <para>This should work on all Unix-like systems such as Linux + and Solaris. For Windows systems, use commands similar to what + is used in the Makefile.</para> + + <para>This will compile the + <computeroutput>clienttest.java</computeroutput> code on the + first call and then execute the resulting + <computeroutput>clienttest</computeroutput> class to show the + locally installed VMs (see below).</para> + </listitem> + </orderedlist></para> + + <para>The <computeroutput>clienttest</computeroutput> sample + imitates a few typical command line tasks that + <computeroutput>VBoxManage</computeroutput>, VirtualBox's regular + command-line front-end, would provide (see the VirtualBox User + Manual for details). In particular, you can run:<itemizedlist> + <listitem> + <para><computeroutput>java clienttest show + vms</computeroutput>: show the virtual machines that are + registered locally.</para> + </listitem> + + <listitem> + <para><computeroutput>java clienttest list + hostinfo</computeroutput>: show various information about the + host this VirtualBox installation runs on.</para> + </listitem> + + <listitem> + <para><computeroutput>java clienttest startvm + <vmname|uuid></computeroutput>: start the given virtual + machine.</para> + </listitem> + </itemizedlist></para> + + <para>The <computeroutput>clienttest.java</computeroutput> sample + code illustrates common basic practices how to use the VirtualBox + OOWS for JAX-WS, which we will explain in more detail in the + following chapters.</para> + </sect3> + + <sect3> + <title>Logging on to the web service</title> + + <para>Before a web service client can do anything useful, two + objects need to be created, as can be seen in the + <computeroutput>clienttest</computeroutput> constructor:<orderedlist> + <listitem> + <para>An instance of + <link linkend="IWebsessionManager">IWebsessionManager</link>, + which is an interface provided by the web service to manage + "web sessions" -- that is, stateful connections to the web + service with persistent objects upon which methods can be + invoked.</para> + + <para>In the OOWS for JAX-WS, the IWebsessionManager class + must be constructed explicitly, and a URL must be provided in + the constructor that specifies where the web service (the + server) awaits connections. The code in + <computeroutput>clienttest.java</computeroutput> connects to + "http://localhost:18083/", which is the default.</para> + + <para>The port number, by default 18083, must match the port + number given to the + <computeroutput>vboxwebsrv</computeroutput> command line; see + <xref linkend="vboxwebsrv-ref"/>.</para> + </listitem> + + <listitem> + <para>After that, the code calls + <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link>, + which is the first call that actually communicates with the + server. This authenticates the client with the web service and + returns an instance of + <link linkend="IVirtualBox">IVirtualBox</link>, + the most fundamental interface of the VirtualBox web service, + from which all other functionality can be derived.</para> + + <para>If logon doesn't work, please take another look at <xref + linkend="websrv_authenticate"/>.</para> + </listitem> + </orderedlist></para> + </sect3> + + <sect3> + <title>Object management</title> + + <para>The current OOWS for JAX-WS has certain memory management + related limitations. When you no longer need an object, call its + <link linkend="IManagedObjectRef__release">IManagedObjectRef::release()</link> + method explicitly, which + frees appropriate managed reference, as is required by the raw + web service; see <xref linkend="managed-object-references"/> for + details. This limitation may be reconsidered in a future version of + the VirtualBox SDK.</para> + </sect3> + </sect2> + + <sect2 id="glue-python-ws"> + <title>The object-oriented web service for Python</title> + + <para>VirtualBox comes with two flavors of a Python API: one for web + service, discussed here, and one for the COM/XPCOM API discussed in + <xref linkend="pycom"/>. The client code is mostly similar, except + for the initialization part, so it is up to the application developer + to choose the appropriate technology. Moreover, a common Python glue + layer exists, abstracting out concrete platform access details, see + <xref linkend="glue-python"/>.</para> + + <para>The minimum supported Python version is 2.6.</para> + + <para>As indicated in <xref linkend="webservice-or-com"/>, the + COM/XPCOM API gives better performance without the SOAP overhead, and + does not require a web server to be running. On the other hand, the + COM/XPCOM Python API requires a suitable Python bridge for your Python + installation (VirtualBox ships the most important ones for each + platform<footnote> + <para>On On Mac OS X only the Python versions bundled with the OS + are officially supported. This means 2.6 and 2.7 for 10.9 and later.</para> + </footnote>). On Windows, you can use the Main API from Python if the + Win32 extensions package for Python<footnote> + <para>See <ulink + url="http://sourceforge.net/project/showfiles.php?group_id=78018">http://sourceforge.net/project/showfiles.php?group_id=78018</ulink>.</para> + </footnote> is installed. Versions of Python Win32 extensions earlier + than 2.16 are known to have bugs, leading to issues with VirtualBox + Python bindings, so please make sure to use latest available Python + and Win32 extensions.</para> + + <para>The VirtualBox OOWS for Python relies on the Python ZSI SOAP + implementation (see <ulink + url="http://pywebsvcs.sourceforge.net/zsi.html">http://pywebsvcs.sourceforge.net/zsi.html</ulink>), + which you will need to install locally before trying the examples. + Most Linux distributions come with package for ZSI, such as + <computeroutput>python-zsi</computeroutput> in Ubuntu.</para> + + <para>To get started, open a terminal and change to the + <computeroutput>bindings/glue/python/sample</computeroutput> + directory, which contains an example of a simple interactive shell + able to control a VirtualBox instance. The shell is written using the + API layer, thereby hiding different implementation details, so it is + actually an example of code share among XPCOM, MSCOM and web services. + If you are interested in how to interact with the web services layer + directly, have a look at + <computeroutput>install/vboxapi/__init__.py</computeroutput> which + contains the glue layer for all target platforms (i.e. XPCOM, MSCOM + and web services).</para> + + <para>To start the shell, perform the following commands: + <screen>/opt/VirtualBox/vboxwebsrv -t 0 + # start web service with object autocollection disabled +export VBOX_PROGRAM_PATH=/opt/VirtualBox + # your VirtualBox installation directory +export VBOX_SDK_PATH=/home/youruser/vbox-sdk + # where you've extracted the SDK +./vboxshell.py -w </screen> + See <xref linkend="vboxshell"/> for more + details on the shell's functionality. For you, as a VirtualBox + application developer, the vboxshell sample could be interesting as an + example of how to write code targeting both local and remote cases + (COM/XPCOM and SOAP). The common part of the shell is the same -- the + only difference is how it interacts with the invocation layer. You can + use the <computeroutput>connect</computeroutput> shell command to + connect to remote VirtualBox servers; in this case you can skip + starting the local web server.</para> + </sect2> + + <sect2> + <title>The object-oriented web service for PHP</title> + + <para>VirtualBox also comes with object-oriented web service (OOWS) + wrappers for PHP5. These wrappers rely on the PHP SOAP + Extension<footnote> + <para>See + <ulink url="https://www.php.net/soap">https://www.php.net/soap</ulink>.</para> + </footnote>, which can be installed by configuring PHP with + <computeroutput>--enable-soap</computeroutput>.</para> + </sect2> + </sect1> + + <sect1 id="raw-webservice"> + <title>Using the raw web service with any language</title> + + <para>The following examples show you how to use the raw web service, + without the object-oriented client-side code that was described in the + previous chapter.</para> + + <para>Generally, when reading the documentation in <xref + linkend="sdkref_classes"/> and <xref linkend="sdkref_enums"/>, due to + the limitations of SOAP and WSDL lined out in <xref + linkend="rawws-conventions"/>, please have the following notes in + mind:</para> + + <para><orderedlist> + <listitem> + <para>Any COM method call becomes a <emphasis role="bold">plain + function call</emphasis> in the raw web service, with the object + as an additional first parameter (before the "real" parameters + listed in the documentation). So when the documentation says that + the <computeroutput>IVirtualBox</computeroutput> interface + supports the <computeroutput>createMachine()</computeroutput> + method (see + <link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link>), + the web service operation is + <computeroutput>IVirtualBox_createMachine(...)</computeroutput>, + and a managed object reference to an + <computeroutput>IVirtualBox</computeroutput> object must be passed + as the first argument.</para> + </listitem> + + <listitem> + <para>For <emphasis role="bold">attributes</emphasis> in + interfaces, there will be at least one "get" function; there will + also be a "set" function, unless the attribute is "readonly". The + attribute name will be appended to the "get" or "set" prefix, with + a capitalized first letter. So, the "version" readonly attribute + of the <computeroutput>IVirtualBox</computeroutput> interface can + be retrieved by calling + <computeroutput>IVirtualBox_getVersion(vbox)</computeroutput>, + with <computeroutput>vbox</computeroutput> being the VirtualBox + object.</para> + </listitem> + + <listitem> + <para>Whenever the API documentation says that a method (or an + attribute getter) returns an <emphasis + role="bold">object</emphasis>, it will returned a managed object + reference in the web service instead. As said above, managed + object references should be released if the web service client + does not log off again immediately!</para> + </listitem> + </orderedlist></para> + + <para></para> + + <sect2 id="webservice-java-sample"> + <title>Raw web service example for Java with Axis</title> + + <para>Axis is an older web service toolkit created by the Apache + foundation. If your distribution does not have it installed, you can + get a binary from <ulink + url="http://www.apache.org">http://www.apache.org</ulink>. The + following examples assume that you have Axis 1.4 installed.</para> + + <para>The VirtualBox SDK ships with an example for Axis that, again, + is called <computeroutput>clienttest.java</computeroutput> and that + imitates a few of the commands of + <computeroutput>VBoxManage</computeroutput> over the wire.</para> + + <para>Then perform the following steps:<orderedlist> + <listitem> + <para>Create a working directory somewhere. Under your + VirtualBox installation directory, find the + <computeroutput>sdk/webservice/samples/java/axis/</computeroutput> + directory and copy the file + <computeroutput>clienttest.java</computeroutput> to your working + directory.</para> + </listitem> + + <listitem> + <para>Open a terminal in your working directory. Execute the + following command: + <screen>java org.apache.axis.wsdl.WSDL2Java /path/to/vboxwebService.wsdl</screen></para> + + <para>The <computeroutput>vboxwebService.wsdl</computeroutput> + file should be located in the + <computeroutput>sdk/webservice/</computeroutput> + directory.</para> + + <para>If this fails, your Apache Axis may not be located on your + system classpath, and you may have to adjust the CLASSPATH + environment variable. Something like this: + <screen>export CLASSPATH="/path-to-axis-1_4/lib/*":$CLASSPATH</screen></para> + + <para>Use the directory where the Axis JAR files are located. + Mind the quotes so that your shell passes the "*" character to + the java executable without expanding. Alternatively, add a + corresponding <computeroutput>-classpath</computeroutput> + argument to the "java" call above.</para> + + <para>If the command executes successfully, you should see an + "org" directory with subdirectories containing Java source files + in your working directory. These classes represent the + interfaces that the VirtualBox web service offers, as described + by the WSDL file.</para> + + <para>This is the bit that makes using web services so + attractive to client developers: if a language's toolkit + understands WSDL, it can generate large amounts of support code + automatically. Clients can then easily use this support code and + can be done with just a few lines of code.</para> + </listitem> + + <listitem> + <para>Next, compile the + <computeroutput>clienttest.java</computeroutput> + source:<screen>javac clienttest.java </screen></para> + + <para>This should yield a "clienttest.class" file.</para> + </listitem> + + <listitem> + <para>To start the VirtualBox web service, open a second + terminal and change to the directory where the VirtualBox + executables are located. Then type: + <screen>./vboxwebsrv -v</screen></para> + + <para>The web service now waits for connections and will run + until you press Ctrl+C in this second terminal. The -v argument + causes it to log all connections to the terminal. (See <xref + linkend="runvboxwebsrv"/> for details on how to run the + web service.)</para> + </listitem> + + <listitem> + <para>Back in the original terminal where you compiled the Java + source, run the resulting binary, which will then connect to the + web service:<screen>java clienttest</screen></para> + + <para>The client sample will connect to the web service (on + localhost, but the code could be changed to connect remotely if + the web service was running on a different machine) and make a + number of method calls. It will output the version number of + your VirtualBox installation and a list of all virtual machines + that are currently registered (with a bit of seemingly random + data, which will be explained later).</para> + </listitem> + </orderedlist></para> + </sect2> + + <sect2 id="raw-webservice-perl"> + <title>Raw web service example for Perl</title> + + <para>We also ship a small sample for Perl. It uses the SOAP::Lite + perl module to communicate with the VirtualBox web service.</para> + + <para>The + <computeroutput>sdk/bindings/webservice/perl/lib/</computeroutput> + directory contains a pre-generated Perl module that allows for + communicating with the web service from Perl. You can generate such a + module yourself using the "stubmaker" tool that comes with SOAP::Lite, + but since that tool is slow as well as sometimes unreliable, we are + shipping a working module with the SDK for your convenience.</para> + + <para>Perform the following steps:<orderedlist> + <listitem> + <para>If SOAP::Lite is not yet installed on your system, you + will need to install the package first. On Debian-based systems, + the package is called + <computeroutput>libsoap-lite-perl</computeroutput>; on Gentoo, + it's <computeroutput>dev-perl/SOAP-Lite</computeroutput>.</para> + </listitem> + + <listitem> + <para>Open a terminal in the + <computeroutput>sdk/bindings/webservice/perl/samples/</computeroutput> + directory.</para> + </listitem> + + <listitem> + <para>To start the VirtualBox web service, open a second + terminal and change to the directory where the VirtualBox + executables are located. Then type: + <screen>./vboxwebsrv -v</screen></para> + + <para>The web service now waits for connections and will run + until you press Ctrl+C in this second terminal. The -v argument + causes it to log all connections to the terminal. (See <xref + linkend="runvboxwebsrv"/> for details on how to run the + web service.)</para> + </listitem> + + <listitem> + <para>In the first terminal with the Perl sample, run the + clienttest.pl script: + <screen>perl -I ../lib clienttest.pl</screen></para> + </listitem> + </orderedlist></para> + </sect2> + + <sect2> + <title>Programming considerations for the raw web service</title> + + <para>If you use the raw web service, you need to keep a number of + things in mind, or you will sooner or later run into issues that are + not immediately obvious. By contrast, the object-oriented client-side + libraries described in <xref linkend="glue"/> take care of these + things automatically and thus greatly simplify using the web + service.</para> + + <sect3 id="rawws-conventions"> + <title>Fundamental conventions</title> + + <para>If you are familiar with other web services, you may find the + VirtualBox web service to behave a bit differently to accommodate + for the fact that VirtualBox web service more or less maps the + VirtualBox Main COM API. The following main differences had to be + taken care of:<itemizedlist> + <listitem> + <para>Web services, as expressed by WSDL, are not + object-oriented. Even worse, they are normally stateless (or, + in web services terminology, "loosely coupled"). Web service + operations are entirely procedural, and one cannot normally + make assumptions about the state of a web service between + function calls.</para> + + <para>In particular, this normally means that you cannot work + on objects in one method call that were created by another + call.</para> + </listitem> + + <listitem> + <para>By contrast, the VirtualBox Main API, being expressed in + COM, is object-oriented and works entirely on objects, which + are grouped into public interfaces, which in turn have + attributes and methods associated with them.</para> + </listitem> + </itemizedlist> For the VirtualBox web service, this results in + three fundamental conventions:<orderedlist> + <listitem> + <para>All <emphasis role="bold">function names</emphasis> in + the VirtualBox web service consist of an interface name and a + method name, joined together by an underscore. This is because + there are only functions ("operations") in WSDL, but no + classes, interfaces, or methods.</para> + + <para>In addition, all calls to the VirtualBox web service + (except for logon, see below) take a <emphasis + role="bold">managed object reference</emphasis> as the first + argument, representing the object upon which the underlying + method is invoked. (Managed object references are explained in + detail below; see <xref + linkend="managed-object-references"/>.)</para> + + <para>So, when one would normally code, in the pseudo-code of + an object-oriented language, to invoke a method upon an + object:<screen>IMachine machine; +result = machine.getName();</screen></para> + + <para>In the VirtualBox web service, this looks something like + this (again, pseudo-code):<screen>IMachineRef machine; +result = IMachine_getName(machine);</screen></para> + </listitem> + + <listitem> + <para>To make the web service stateful, and objects persistent + between method calls, the VirtualBox web service introduces a + <emphasis role="bold">session manager</emphasis> (by way of the + <link linkend="IWebsessionManager">IWebsessionManager</link> + interface), which manages object references. Any client wishing + to interact with the web service must first log on to the + session manager and in turn receives a managed object reference + to an object that supports the + <link linkend="IVirtualBox">IVirtualBox</link> + interface (the basic interface in the Main API).</para> + </listitem> + </orderedlist></para> + + <para>In other words, as opposed to other web services, <emphasis + role="bold">the VirtualBox web service is both object-oriented and + stateful.</emphasis></para> + </sect3> + + <sect3> + <title>Example: A typical web service client session</title> + + <para>A typical short web service session to retrieve the version + number of the VirtualBox web service (to be precise, the underlying + Main API version number) looks like this:<orderedlist> + <listitem> + <para>A client logs on to the web service by calling + <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link> + with a valid user name and password. See + <xref linkend="websrv_authenticate"/> + for details about how authentication works.</para> + </listitem> + + <listitem> + <para>On the server side, + <computeroutput>vboxwebsrv</computeroutput> creates a session, + which persists until the client calls + <link linkend="IWebsessionManager__logoff">IWebsessionManager::logoff()</link> + or the session times out after a configurable period of + inactivity (see <xref linkend="vboxwebsrv-ref"/>).</para> + + <para>For the new session, the web service creates an instance + of <link linkend="IVirtualBox">IVirtualBox</link>. + This interface is the most central one in the Main API and + allows access to all other interfaces, either through + attributes or method calls. For example, IVirtualBox contains + a list of all virtual machines that are currently registered + (as they would be listed on the left side of the VirtualBox + main program).</para> + + <para>The web service then creates a managed object reference + for this instance of IVirtualBox and returns it to the calling + client, which receives it as the return value of the logon + call. Something like this:</para> + + <screen>string oVirtualBox; +oVirtualBox = webservice.IWebsessionManager_logon("user", "pass");</screen> + + <para>(The managed object reference "oVirtualBox" is just a + string consisting of digits and dashes. However, it is a + string with a meaning and will be checked by the web service. + For details, see below. As hinted above, + <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link> + is the <emphasis>only</emphasis> operation provided by the web + service which does not take a managed object reference as the + first argument!)</para> + </listitem> + + <listitem> + <para>The VirtualBox Main API documentation says that the + <computeroutput>IVirtualBox</computeroutput> interface has a + <link linkend="IVirtualBox__version">version</link> + attribute, which is a string. For each attribute, there is a + "get" and a "set" method in COM, which maps to according + operations in the web service. So, to retrieve the "version" + attribute of this <computeroutput>IVirtualBox</computeroutput> + object, the web service client does this: + <screen>string version; +version = webservice.IVirtualBox_getVersion(oVirtualBox); + +print version;</screen></para> + + <para>And it will print + "&VBOX_VERSION_MAJOR;.&VBOX_VERSION_MINOR;.&VBOX_VERSION_BUILD;".</para> + </listitem> + + <listitem> + <para>The web service client calls + <link linkend="IWebsessionManager__logoff">IWebsessionManager::logoff()</link> + with the VirtualBox managed object reference. This will clean + up all allocated resources.</para> + </listitem> + </orderedlist></para> + </sect3> + + <sect3 id="managed-object-references"> + <title>Managed object references</title> + + <para>To a web service client, a managed object reference looks like + a string: two 64-bit hex numbers separated by a dash. This string, + however, represents a COM object that "lives" in the web service + process. The two 64-bit numbers encoded in the managed object + reference represent a session ID (which is the same for all objects + in the same web service session, i.e. for all objects after one + logon) and a unique object ID within that session.</para> + + <para>Managed object references are created in two + situations:<orderedlist> + <listitem> + <para>When a client logs on, by calling + <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link>.</para> + + <para>Upon logon, the websession manager creates one instance + of <link linkend="IVirtualBox">IVirtualBox</link>, + which can be used for directly performing calls to its + methods, or used as a parameter for calling some methods of + <link linkend="IWebsessionManager">IWebsessionManager</link>. + Creating Main API session objects is performed using + <link linkend="IWebsessionManager__getSessionObject">IWebsessionManager::getSessionObject()</link>.</para> + + <para>(Technically, there is always only one + <link linkend="IVirtualBox">IVirtualBox</link> object, which + is shared between all websessions and clients, as it is a COM + singleton. However, each session receives its own managed + object reference to it.)</para> + </listitem> + + <listitem> + <para>Whenever a web service clients invokes an operation + whose COM implementation creates COM objects.</para> + + <para>For example, + <link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link> + creates a new instance of + <link linkend="IMachine">IMachine</link>; + the COM object returned by the COM method call is then wrapped + into a managed object reference by the web server, and this + reference is returned to the web service client.</para> + </listitem> + </orderedlist></para> + + <para>Internally, in the web service process, each managed object + reference is simply a small data structure, containing a COM pointer + to the "real" COM object, the web session ID and the object ID. This + structure is allocated on creation and stored efficiently in hashes, + so that the web service can look up the COM object quickly whenever + a web service client wishes to make a method call. The random + session ID also ensures that one web service client cannot intercept + the objects of another.</para> + + <para>Managed object references are not destroyed automatically and + must be released by explicitly calling + <link linkend="IManagedObjectRef__release">IManagedObjectRef::release()</link>. + This is important, as + otherwise hundreds or thousands of managed object references (and + corresponding COM objects, which can consume much more memory!) can + pile up in the web service process and eventually cause it to deny + service.</para> + + <para>To reiterate: The underlying COM object, which the reference + points to, is only freed if the managed object reference is + released. It is therefore vital that web service clients properly + clean up after the managed object references that are returned to + them.</para> + + <para>When a web service client calls + <link linkend="IWebsessionManager__logoff">IWebsessionManager::logoff()</link>, + all managed object references created during the session are + automatically freed. For short-lived sessions that do not create a + lot of objects, logging off may therefore be sufficient, although it + is certainly not "best practice".</para> + </sect3> + + <sect3> + <title>Some more detail about web service operation</title> + + <sect4 id="soap"> + <title>SOAP messages</title> + + <para>Whenever a client makes a call to a web service, this + involves a complicated procedure internally. These calls are + remote procedure calls. Each such procedure call typically + consists of two "message" being passed, where each message is a + plain-text HTTP request with a standard HTTP header and a special + XML document following. This XML document encodes the name of the + procedure to call and the argument names and values passed to + it.</para> + + <para>To give you an idea of what such a message looks like, + assuming that a web service provides a procedure called + "SayHello", which takes a string "name" as an argument and returns + "Hello" with a space and that name appended, the request message + could look like this:</para> + + <para><screen><?xml version="1.0" encoding="UTF-8"?> +<SOAP-ENV:Envelope + xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" + xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:xsd="http://www.w3.org/2001/XMLSchema" + xmlns:test="http://test/"> +<SOAP-ENV:Body> + <test:SayHello> + <name>Peter</name> + </test:SayHello> + </SOAP-ENV:Body> +</SOAP-ENV:Envelope></screen>A similar message -- the "response" message + -- would be sent back from the web service to the client, + containing the return value "Hello Peter".</para> + + <para>Most programming languages provide automatic support to + generate such messages whenever code in that programming language + makes such a request. In other words, these programming languages + allow for writing something like this (in pseudo-C++ code):</para> + + <para><screen>webServiceClass service("localhost", 18083); // server and port +string result = service.SayHello("Peter"); // invoke remote procedure</screen> + and would, for these two pseudo-lines, automatically perform these + steps:</para> + + <para><orderedlist> + <listitem> + <para>prepare a connection to a web service running on port + 18083 of "localhost";</para> + </listitem> + + <listitem> + <para>for the <computeroutput>SayHello()</computeroutput> + function of the web service, generate a SOAP message like in + the above example by encoding all arguments of the remote + procedure call (which could involve all kinds of type + conversions and complex marshalling for arrays and + structures);</para> + </listitem> + + <listitem> + <para>connect to the web service via HTTP and send that + message;</para> + </listitem> + + <listitem> + <para>wait for the web service to send a response + message;</para> + </listitem> + + <listitem> + <para>decode that response message and put the return value + of the remote procedure into the "result" variable.</para> + </listitem> + </orderedlist></para> + </sect4> + + <sect4 id="wsdl"> + <title>Service descriptions in WSDL</title> + + <para>In the above explanations about SOAP, it was left open how + the programming language learns about how to translate function + calls in its own syntax into proper SOAP messages. In other words, + the programming language needs to know what operations the web + service supports and what types of arguments are required for the + operation's data in order to be able to properly serialize and + deserialize the data to and from the web service. For example, if + a web service operation expects a number in "double" floating + point format for a particular parameter, the programming language + cannot send to it a string instead.</para> + + <para>For this, the Web Service Definition Language (WSDL) was + invented, another XML substandard that describes exactly what + operations the web service supports and, for each operation, which + parameters and types are needed with each request and response + message. WSDL descriptions can be incredibly verbose, and one of + the few good things that can be said about this standard is that + it is indeed supported by most programming languages.</para> + + <para>So, if it is said that a programming language "supports" web + services, this typically means that a programming language has + support for parsing WSDL files and somehow integrating the remote + procedure calls into the native language syntax -- for example, + like in the Java sample shown in <xref + linkend="webservice-java-sample"/>.</para> + + <para>For details about how programming languages support web + services, please refer to the documentation that comes with the + individual languages. Here are a few pointers:</para> + + <orderedlist> + <listitem> + <para>For <emphasis role="bold">C++, </emphasis> among many + others, the gSOAP toolkit is a good option. Parts of gSOAP are + also used in VirtualBox to implement the VirtualBox web + service.</para> + </listitem> + + <listitem> + <para>For <emphasis role="bold">Java, </emphasis> there are + several implementations already described in this document + (see <xref linkend="glue-jax-ws"/> and <xref + linkend="webservice-java-sample"/>).</para> + </listitem> + + <listitem> + <para><emphasis role="bold">Perl</emphasis> supports WSDL via + the SOAP::Lite package. This in turn comes with a tool called + <computeroutput>stubmaker.pl</computeroutput> that allows you + to turn any WSDL file into a Perl package that you can import. + (You can also import any WSDL file "live" by having it parsed + every time the script runs, but that can take a while.) You + can then code (again, assuming the above example): + <screen>my $result = servicename->sayHello("Peter");</screen> + </para> + + <para>A sample that uses SOAP::Lite was described in <xref + linkend="raw-webservice-perl"/>.</para> + </listitem> + </orderedlist> + </sect4> + </sect3> + </sect2> + </sect1> + + <sect1 id="api_com"> + <title>Using COM/XPCOM directly</title> + + <para>If you do not require <emphasis>remote</emphasis> procedure calls + such as those offered by the VirtualBox web service, and if you know + Python or C++ as well as COM, you might find it preferable to program + VirtualBox's Main API directly via COM.</para> + + <para>COM stands for "Component Object Model" and is a standard + originally introduced by Microsoft in the 1990s for Microsoft Windows. + It allows for organizing software in an object-oriented way and across + processes; code in one process may access objects that live in another + process.</para> + + <para>COM has several advantages: it is language-neutral, meaning that + even though all of VirtualBox is internally written in C++, programs + written in other languages could communicate with it. COM also cleanly + separates interface from implementation, so that external programs need + not know anything about the messy and complicated details of VirtualBox + internals.</para> + + <para>On a Windows host, all parts of VirtualBox will use the COM + functionality that is native to Windows. On other hosts (including + Linux), VirtualBox comes with a built-in implementation of XPCOM, as + originally created by the Mozilla project, which we have enhanced to + support interprocess communication on a level comparable to Microsoft + COM. Internally, VirtualBox has an abstraction layer that allows the + same VirtualBox code to work both with native COM as well as our XPCOM + implementation.</para> + + <sect2 id="pycom"> + <title>Python COM API</title> + + <para>On Windows, Python scripts can use COM and VirtualBox interfaces + to control almost all aspects of virtual machine execution. As an + example, use the following commands to instantiate the VirtualBox + object and start a VM: <screen> + vbox = win32com.client.Dispatch("VirtualBox.VirtualBox") + session = win32com.client.Dispatch("VirtualBox.Session") + mach = vbox.findMachine("uuid or name of machine to start") + progress = mach.launchVMProcess(session, "gui", "") + progress.waitForCompletion(-1) + </screen> Also, see + <computeroutput>/bindings/glue/python/samples/vboxshell.py</computeroutput> + for more advanced usage scenarious. However, unless you have specific + requirements, we strongly recommend to use the generic glue layer + described in the next section to access MS COM objects.</para> + </sect2> + + <sect2 id="glue-python"> + <title>Common Python bindings layer</title> + + <para>As different wrappers ultimately provide access to the same + underlying API, and to simplify porting and development of Python + application using the VirtualBox Main API, we developed a common glue + layer that abstracts out most platform-specific details from the + application and allows the developer to focus on application logic. + The VirtualBox installer automatically sets up this glue layer for the + system default Python installation.</para> + + <para>See <xref linkend="glue-python-setup"/> for details on how to + set up the glue layer if you want to use a different Python installation, + or if the VirtualBox installer failed to detect and set it up accordingly.</para> + + <para>The minimum supported Python version is 2.6.</para> + + <para>In this layer, the class + <computeroutput>VirtualBoxManager</computeroutput> hides most + platform-specific details. It can be used to access both the local + (COM) and the web service based API. The following code can be used by + an application to use the glue layer.</para> + + <screen># This code assumes vboxapi.py from VirtualBox distribution +# being in PYTHONPATH, or installed system-wide +from vboxapi import VirtualBoxManager + +# This code initializes VirtualBox manager with default style +# and parameters +virtualBoxManager = VirtualBoxManager(None, None) + +# Alternatively, one can be more verbose, and initialize +# glue with web service backend, and provide authentication +# information +virtualBoxManager = VirtualBoxManager("WEBSERVICE", + {'url':'http://myhost.com::18083/', + 'user':'me', + 'password':'secret'}) </screen> + + <para>We supply the <computeroutput>VirtualBoxManager</computeroutput> + constructor with 2 arguments: style and parameters. Style defines + which bindings style to use (could be "MSCOM", "XPCOM" or + "WEBSERVICE"), and if set to <computeroutput>None</computeroutput> + defaults to usable platform bindings (MS COM on Windows, XPCOM on + other platforms). The second argument defines parameters, passed to + the platform-specific module, as we do in the second example, where we + pass username and password to be used to authenticate against the web + service.</para> + + <para>After obtaining the + <computeroutput>VirtualBoxManager</computeroutput> instance, one can + perform operations on the IVirtualBox class. For example, the + following code will a start virtual machine by name or ID:</para> + + <screen>from vboxapi import VirtualBoxManager +mgr = VirtualBoxManager(None, None) +vbox = mgr.getVirtualBox() +name = "Linux" +mach = vbox.findMachine(name) +session = mgr.getSessionObject(vbox) +progress = mach.launchVMProcess(session, "gui", "") +progress.waitForCompletion(-1) +mgr.closeMachineSession(session) + </screen> + <para> + Following code will print all registered machines and their log + folders + </para> + <screen>from vboxapi import VirtualBoxManager +mgr = VirtualBoxManager(None, None) +vbox = mgr.getVirtualBox() + +for m in mgr.getArray(vbox, 'machines'): + print "Machine '%s' logs in '%s'" %(m.name, m.logFolder) + </screen> + + <para>Code above demonstrates cross-platform access to array properties + (certain limitations prevent one from using + <computeroutput>vbox.machines</computeroutput> to access a list of + available virtual machines in case of XPCOM), and a mechanism of + uniform session creation and closing + (<computeroutput>mgr.getSessionObject()</computeroutput>).</para> + + <sect3 id="glue-python-setup"> + <title>Manual or subsequent setup</title> + + <para>In case you want to use the glue layer with a different Python + installation or the installer failed to set it up, use these steps + in a shell to install the necessary files:</para> + + <screen> # cd VBOX_INSTALL_PATH/sdk/installer + # PYTHON vboxapisetup.py install</screen> + + <note> <para>On Windows hosts, a Python distribution along with the + win32api bindings package need to be installed as a prerequisite. </para></note> + </sect3> + + </sect2> + + <sect2 id="cppcom"> + <title>C++ COM API</title> + + <para>C++ is the language that VirtualBox itself is written in, so C++ + is the most direct way to use the Main API -- but it is not + necessarily the easiest, as using COM and XPCOM has its own set of + complications.</para> + + <para>VirtualBox ships with sample programs that demonstrate how to + use the Main API to implement a number of tasks on your host platform. + These samples can be found in the + <computeroutput>/bindings/xpcom/samples</computeroutput> directory for + Linux, Mac OS X and Solaris and + <computeroutput>/bindings/mscom/samples</computeroutput> for Windows. + The two samples are actually different, because the one for Windows + uses native COM, whereas the other uses our XPCOM implementation, as + described above.</para> + + <para>Since COM and XPCOM are conceptually very similar but vary in + the implementation details, we have created a "glue" layer that + shields COM client code from these differences. All VirtualBox uses is + this glue layer, so the same code written once works on both Windows + hosts (with native COM) as well as on other hosts (with our XPCOM + implementation). It is recommended to always use this glue code + instead of using the COM and XPCOM APIs directly, as it is very easy + to make your code completely independent from the platform it is + running on.<!-- A third sample, + <computeroutput>tstVBoxAPIGlue.cpp</computeroutput>, illustrates how to + use the glue layer. +--></para> + + <para>In order to encapsulate platform differences between Microsoft + COM and XPCOM, the following items should be kept in mind when using + the glue layer:</para> + + <para><orderedlist> + <listitem> + <para><emphasis role="bold">Attribute getters and + setters.</emphasis> COM has the notion of "attributes" in + interfaces, which roughly compare to C++ member variables in + classes. The difference is that for each attribute declared in + an interface, COM automatically provides a "get" method to + return the attribute's value. Unless the attribute has been + marked as "readonly", a "set" attribute is also provided.</para> + + <para>To illustrate, the IVirtualBox interface has a "version" + attribute, which is read-only and of the "wstring" type (the + standard string type in COM). As a result, you can call the + "get" method for this attribute to retrieve the version number + of VirtualBox.</para> + + <para>Unfortunately, the implementation differs between COM and + XPCOM. Microsoft COM names the "get" method like this: + <computeroutput>get_Attribute()</computeroutput>, whereas XPCOM + uses this syntax: + <computeroutput>GetAttribute()</computeroutput> (and accordingly + for "set" methods). To hide these differences, the VirtualBox + glue code provides the + <computeroutput>COMGETTER(attrib)</computeroutput> and + <computeroutput>COMSETTER(attrib)</computeroutput> macros. So, + <computeroutput>COMGETTER(version)()</computeroutput> (note, two + pairs of brackets) expands to + <computeroutput>get_Version()</computeroutput> on Windows and + <computeroutput>GetVersion()</computeroutput> on other + platforms.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">Unicode conversions.</emphasis> + While the rest of the modern world has pretty much settled on + encoding strings in UTF-8, COM, unfortunately, uses UCS-16 + encoding. This requires a lot of conversions, in particular + between the VirtualBox Main API and the Qt GUI, which, like the + rest of Qt, likes to use UTF-8.</para> + + <para>To facilitate these conversions, VirtualBox provides the + <computeroutput>com::Bstr</computeroutput> and + <computeroutput>com::Utf8Str</computeroutput> classes, which + support all kinds of conversions back and forth.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">COM autopointers.</emphasis> + Possibly the greatest pain of using COM -- reference counting -- + is alleviated by the + <computeroutput>ComPtr<></computeroutput> template + provided by the <computeroutput>ptr.h</computeroutput> file in + the glue layer.</para> + </listitem> + </orderedlist></para> + </sect2> + + <sect2 id="event-queue"> + <title>Event queue processing</title> + + <para>Both VirtualBox client programs and frontends should + periodically perform processing of the main event queue, and do that + on the application's main thread. In case of a typical GUI Windows/Mac + OS application this happens automatically in the GUI's dispatch loop. + However, for CLI only application, the appropriate actions have to be + taken. For C++ applications, the VirtualBox SDK provided glue method + <screen> + int EventQueue::processEventQueue(uint32_t cMsTimeout) + </screen> can be used for both blocking and non-blocking operations. + For the Python bindings, a common layer provides the method <screen> + VirtualBoxManager.waitForEvents(ms) + </screen> with similar semantics.</para> + + <para>Things get somewhat more complicated for situations where an + application using VirtualBox cannot directly control the main event + loop and the main event queue is separated from the event queue of the + programming librarly (for example in case of Qt on Unix platforms). In + such a case, the application developer is advised to use a + platform/toolkit specific event injection mechanism to force event + queue checks either based on periodical timer events delivered to the + main thread, or by using custom platform messages to notify the main + thread when events are available. See the VBoxSDL and Qt (VirtualBox) + frontends as examples.</para> + </sect2> + + <sect2 id="vbcom"> + <title>Visual Basic and Visual Basic Script (VBS) on Windows + hosts</title> + + <para>On Windows hosts, one can control some of the VirtualBox Main + API functionality from VBS scripts, and pretty much everything from + Visual Basic programs.<footnote> + <para>The difference results from the way VBS treats COM + safearrays, which are used to keep lists in the Main API. VBS + expects every array element to be a + <computeroutput>VARIANT</computeroutput>, which is too strict a + limitation for any high performance API. We may lift this + restriction for interface APIs in a future version, or + alternatively provide conversion APIs.</para> + </footnote></para> + + <para>VBS is scripting language available in any recent Windows + environment. As an example, the following VBS code will print + VirtualBox version: <screen> + set vb = CreateObject("VirtualBox.VirtualBox") + Wscript.Echo "VirtualBox version " & vb.version + </screen> See + <computeroutput>bindings/mscom/vbs/sample/vboxinfo.vbs</computeroutput> + for the complete sample.</para> + + <para>Visual Basic is a popular high level language capable of + accessing COM objects. The following VB code will iterate over all + available virtual machines:<screen> + Dim vb As VirtualBox.IVirtualBox + + vb = CreateObject("VirtualBox.VirtualBox") + machines = "" + For Each m In vb.Machines + m = m & " " & m.Name + Next + </screen> See + <computeroutput>bindings/mscom/vb/sample/vboxinfo.vb</computeroutput> + for the complete sample.</para> + </sect2> + + <sect2 id="cbinding"> + <title>C binding to VirtualBox API</title> + + <para>The VirtualBox API originally is designed as object oriented, + using XPCOM or COM as the middleware, which translates natively to C++. + This means that in order to use it from C there needs to be some + helper code to bridge the language differences and reduce the + differences between platforms.</para> + + <sect3 id="capi_glue"> + <title>Cross-platform C binding to VirtualBox API</title> + + <para>Starting with version 4.3, VirtualBox offers a C binding + which allows using the same C client sources for all platforms, + covering Windows, Linux, Mac OS X and Solaris. It is the + preferred way to write API clients, even though the old style + is still available.</para> + + </sect3> + + <sect3 id="c-gettingstarted"> + <title>Getting started</title> + + <para>The following sections describe how to use the VirtualBox API + in a C program. The necessary files are included in the SDK, in the + directories <computeroutput>sdk/bindings/c/include</computeroutput> + and <computeroutput>sdk/bindings/c/glue</computeroutput>.</para> + + <para>As part of the SDK, a sample program + <computeroutput>tstCAPIGlue.c</computeroutput> is provided in the + directory <computeroutput>sdk/bindings/c/samples</computeroutput> + which demonstrates + using the C binding to initialize the API, get handles for + VirtualBox and Session objects, make calls to list and start virtual + machines, monitor events, and uninitialize resources when done. The + sample program is trying to illustrate all relevant concepts, so it + is a great source of detail information. Among many other generally + useful code sequences it contains a function which shows how to + retrieve error details in C code if they are available from the API + call.</para> + + <para>The sample program <computeroutput>tstCAPIGlue</computeroutput> + can be built using the provided + <computeroutput>Makefile</computeroutput> and can be run without + arguments.</para> + + <para>It uses the VBoxCAPIGlue library (source code is in directory + <computeroutput>sdk/bindings/c/glue</computeroutput>, to be used in + your API client code) to open the C binding layer during runtime, + which is preferred to other means as it isolates the code which + locates the necessary dynamic library, using a known working way + which works on all platforms. If you encounter problems with this + glue code in <computeroutput>VBoxCAPIGlue.c</computeroutput>, let the + VirtualBox developers know, rather than inventing incompatible + solutions.</para> + + <para>The following sections document the important concepts needed + to correctly use the C binding, as it is vital for developing API + client code which manages memory correctly, updates the reference + counters correctly, avoiding crashes and memory leaks. Often API + clients need to handle events, so the C API specifics are also + described below.</para> + </sect3> + + <sect3 id="c-initialization"> + <title>VirtualBox C API initialization</title> + + <para>Just like in C++, the API and the underlying middleware needs + to be initialized before it can be used. The + <computeroutput>VBoxCAPI_v4_3.h</computeroutput> header provides the + interface to the C binding, but you can alternatively and more + conveniently also include + <computeroutput>VBoxCAPIGlue.h</computeroutput>, + as this avoids the VirtualBox version dependent header file name and + makes sure the global variable <code>g_pVBoxFuncs</code> contains a + pointer to the structure which contains the helper function pointers. + Here's how to initialize the C API:<screen>#include "VBoxCAPIGlue.h" +... +IVirtualBoxClient *vboxclient = NULL; +IVirtualBox *vbox = NULL; +ISession *session = NULL; +HRESULT rc; +ULONG revision; + +/* + * VBoxCGlueInit() loads the necessary dynamic library, handles errors + * (producing an error message hinting what went wrong) and gives you + * the pointer to the function table (g_pVBoxFuncs). + * + * Once you get the function table, then how and which functions + * to use is explained below. + * + * g_pVBoxFuncs->pfnClientInitialize does all the necessary startup + * action and provides us with pointers to an IVirtualBoxClient instance. + * It should be matched by a call to g_pVBoxFuncs->pfnClientUninitialize() + * when done. + */ + +if (VBoxCGlueInit()) +{ + fprintf(stderr, "s: FATAL: VBoxCGlueInit failed: %s\n", + argv[0], g_szVBoxErrMsg); + return EXIT_FAILURE; +} + +g_pVBoxFuncs->pfnClientInitialize(NULL, &vboxclient); +if (!vboxclient) +{ + fprintf(stderr, "%s: FATAL: could not get VirtualBoxClient reference\n", + argv[0]); + return EXIT_FAILURE; +}</screen></para> + + <para>If <computeroutput>vboxclient</computeroutput> is still + <computeroutput>NULL</computeroutput> this means the initializationi + failed and the VirtualBox C API cannot be used.</para> + + <para>It is possible to write C applications using multiple threads + which all use the VirtualBox API, as long as you're initializing + the C API in each thread which your application creates. This is done + with <code>g_pVBoxFuncs->pfnClientThreadInitialize()</code> and + likewise before the thread is terminated the API must be + uninitialized with + <code>g_pVBoxFuncs->pfnClientThreadUninitialize()</code>. You don't + have to use these functions in worker threads created by COM/XPCOM + (which you might observe if your code uses active event handling), + everything is initialized correctly already. On Windows the C + bindings create a marshaller which supports a wide range of COM + threading models, from STA to MTA, so you don't have to worry about + these details unless you plan to use active event handlers. See + the sample code how to get this to work reliably (in other words + think twice if passive event handling isn't the better solution after + you looked at the sample code).</para> + </sect3> + + <sect3 id="c-invocation"> + <title>C API attribute and method invocation</title> + + <para>Method invocation is straightforward. It looks pretty much + like the C++ way, by using a macro which internally accesses the + vtable, and additionally needs to be passed a pointer to the objecti + as the first argument to serve as the + <computeroutput>this</computeroutput> pointer.</para> + + <para>Using the C binding, all method invocations return a numeric + result code of type <code>HRESULT</code> (with a few exceptions + which normally are not relevant).</para> + + <para>If an interface is specified as returning an object, a pointer + to a pointer to the appropriate object must be passed as the last + argument. The method will then store an object pointer in that + location.</para> + + <para>Likewise, attributes (properties) can be queried or set using + method invocations, using specially named methods. For each + attribute there exists a getter method, the name of which is composed + of <computeroutput>get_</computeroutput> followed by the capitalized + attribute name. Unless the attribute is read-only, an analogous + <computeroutput>set_</computeroutput> method exists. Let's apply + these rules to get the <computeroutput>IVirtualBox</computeroutput> + reference, an <computeroutput>ISession</computeroutput> instance + reference and read the + <link linkend="IVirtualBox__revision">IVirtualBox::revision</link> + attribute: + <screen>rc = IVirtualBoxClient_get_VirtualBox(vboxclient, &vbox); +if (FAILED(rc) || !vbox) +{ + PrintErrorInfo(argv[0], "FATAL: could not get VirtualBox reference", rc); + return EXIT_FAILURE; +} +rc = IVirtualBoxClient_get_Session(vboxclient, &session); +if (FAILED(rc) || !session) +{ + PrintErrorInfo(argv[0], "FATAL: could not get Session reference", rc); + return EXIT_FAILURE; +} + +rc = IVirtualBox_get_Revision(vbox, &revision); +if (SUCCEEDED(rc)) +{ + printf("Revision: %u\n", revision); +}</screen></para> + + <para>The convenience macros for calling a method are named by + prepending the method name with the interface name (using + <code>_</code>as the separator).</para> + + <para>So far only attribute getters were illustrated, but generic + method calls are straightforward, too: + <screen>IMachine *machine = NULL; +BSTR vmname = ...; +... +/* + * Calling IMachine::findMachine(...) + */ +rc = IVirtualBox_FindMachine(vbox, vmname, &machine);</screen></para> + + <para>As a more complicated example of a method invocation, let's + call + <link linkend="IMachine__launchVMProcess">IMachine::launchVMProcess</link> + which returns an IProgress object. Note again that the method name is + capitalized: + <screen>IProgress *progress; +... +rc = IMachine_LaunchVMProcess( + machine, /* this */ + session, /* arg 1 */ + sessionType, /* arg 2 */ + env, /* arg 3 */ + &progress /* Out */ +);</screen></para> + + <para>All objects with their methods and attributes are documented + in <xref linkend="sdkref_classes"/>.</para> + </sect3> + + <sect3 id="c-string-handling"> + <title>String handling</title> + + <para>When dealing with strings you have to be aware of a string's + encoding and ownership.</para> + + <para>Internally, the API uses UTF-16 encoded strings. A set of + conversion functions is provided to convert other encodings to and + from UTF-16. The type of a UTF-16 character is + <computeroutput>BSTR</computeroutput> (or its constant counterpart + <computeroutput>CBSTR</computeroutput>), which is an array type, + represented by a pointer to the start of the zero-terminated string. + There are functions for converting between UTF-8 and UTF-16 strings + available through <code>g_pVBoxFuncs</code>: + <screen>int (*pfnUtf16ToUtf8)(CBSTR pwszString, char **ppszString); +int (*pfnUtf8ToUtf16)(const char *pszString, BSTR *ppwszString);</screen></para> + + <para>The ownership of a string determines who is responsible for + releasing resources associated with the string. Whenever the API + creates a string (essentially for output parameters), ownership is + transferred to the caller. To avoid resource leaks, the caller + should release resources once the string is no longer needed. + There are plenty of examples in the sample code.</para> + </sect3> + + <sect3 id="c-safearray"> + <title>Array handling</title> + + <para>Arrays are handled somewhat similarly to strings, with the + additional information of the number of elements in the array. The + exact details of string passing depends on the platform middleware + (COM/XPCOM), and therefore the C binding offers helper functions to + gloss over these differences.</para> + + <para>Passing arrays as input parameters to API methods is usually + done by the following sequence, calling a hypothetical + <code>IArrayDemo_PassArray</code> API method: + <screen>static const ULONG aElements[] = { 1, 2, 3, 4 }; +ULONG cElements = sizeof(aElements) / sizeof(aElements[0]); +SAFEARRAY *psa = NULL; +psa = g_pVBoxFuncs->pfnSafeArrayCreateVector(VT_I4, 0, cElements); +g_pVBoxFuncs->pfnSafeArrayCopyInParamHelper(psa, aElements, sizeof(aElements)); +IArrayDemo_PassArray(pThis, ComSafeArrayAsInParam(psa)); +g_pVBoxFuncs->pfnSafeArrayDestroy(psa);</screen></para> + + <para>Likewise, getting arrays results from output parameters is done + using helper functions which manage memory allocations as part of + their other functionality: + <screen>SAFEARRAY *psa = g_pVBoxFuncs->pfnSafeArrayOutParamAlloc(); +ULONG *pData; +ULONG cElements; +IArrayDemo_ReturnArray(pThis, ComSafeArrayAsOutTypeParam(psa, ULONG)); +g_pVBoxFuncs->pfnSafeArrayCopyOutParamHelper((void **)&pData, &cElements, VT_I4, psa); +g_pVBoxFuncs->pfnSafeArrayDestroy(psa);</screen></para> + + <para>This covers the necessary functionality for all array element + types except interface references. These need special helpers to + manage the reference counting correctly. The following code snippet + gets the list of VMs, and passes the first IMachine reference to + another API function (assuming that there is at least one element + in the array, to simplify the example): + <screen>SAFEARRAY psa = g_pVBoxFuncs->pfnSafeArrayOutParamAlloc(); +IMachine **machines = NULL; +ULONG machineCnt = 0; +ULONG i; +IVirtualBox_get_Machines(virtualBox, ComSafeArrayAsOutIfaceParam(machinesSA, IMachine *)); +g_pVBoxFuncs->pfnSafeArrayCopyOutIfaceParamHelper((IUnknown ***)&machines, &machineCnt, machinesSA); +g_pVBoxFuncs->pfnSafeArrayDestroy(machinesSA); +/* Now "machines" contains the IMachine references, and machineCnt the + * number of elements in the array. */ +... +SAFEARRAY *psa = g_pVBoxFuncs->pfnSafeArrayCreateVector(VT_IUNKNOWN, 0, 1); +g_pVBoxFuncs->pfnSafeArrayCopyInParamHelper(psa, (void *)&machines[0], sizeof(machines[0])); +IVirtualBox_GetMachineStates(ComSafeArrayAsInParam(psa), ...); +... +g_pVBoxFuncs->pfnSafeArrayDestroy(psa); +for (i = 0; i < machineCnt; ++i) +{ + IMachine *machine = machines[i]; + IMachine_Release(machine); +} +free(machines);</screen></para> + + <para>Handling output parameters needs more special effort than + input parameters, thus only for the former there are special helpers, + and the latter is handled through the generic array support.</para> + </sect3> + + <sect3 id="c-eventhandling"> + <title>Event handling</title> + + <para>The VirtualBox API offers two types of event handling, active + and passive, and consequently there is support for both with the + C API binding. Active event handling (based on asynchronous + callback invocation for event delivery) is more difficult, as it + requires the construction of valid C++ objects in C, which is + inherently platform and compiler dependent. Passive event handling + is much simpler, it relies on an event loop, fetching events and + triggering the necessary handlers explicitly in the API client code. + Both approaches depend on an event loop to make sure that events + get delivered in a timely manner, with differences what exactly needs + to be done.</para> + + <para>The C API sample contains code for both event handling styles, + and one has to modify the appropriate <code>#define</code> to select + which style is actually used by the compiled program. It allows a + good comparison between the two variants, and the code sequences are + probably worth reusing without much change in other API clients + with only minor adaptions.</para> + + <para>Active event handling needs to ensure that the following helper + function is called frequently enough in the primary thread: + <screen>g_pVBoxFuncs->pfnProcessEventQueue(cTimeoutMS);</screen></para> + + <para>The actual event handler implementation is quite tedious, as + it has to implement a complete API interface. Especially on Windows + it is a lot of work to implement the complicated + <code>IDispatch</code> interface, requiring to load COM type + information and using it in the <code>IDispatch</code> method + implementation. Overall this is quite tedious compared to passive + event handling.</para> + + <para>Passive event handling uses a similar event loop structure, + which requires calling the following function in a loop, and + processing the returned event appropriately: + <screen>rc = IEventSource_GetEvent(pEventSource, pListener, cTimeoutMS, &pEvent);</screen></para> + + <para>After processing the event it needs to be marked as processed + with the following method call: + <screen>rc = IEventSource_EventProcessed(pEventSource, pListener, pEvent);</screen></para> + + <para>This is vital for vetoable events, as they would be stuck + otherwise, waiting whether the veto comes or not. It does not do any + harm for other event types, and in the end is cheaper than checking + if the event at hand is vetoable or not.</para> + + <para>The general event handling concepts are described in the API + specification (see <xref linkend="events"/>), including how to + aggregate multiple event sources for processing in one event loop. + As mentioned, the sample illustrates the practical aspects of how to + use both types of event handling, active and passive, from a C + application. Additional hints are in the comments documenting + the helper methods in + <computeroutput>VBoxCAPI_v4_3.h</computeroutput>. The code complexity + of active event handling (and its inherenly platform/compiler + specific aspects) should be motivation to use passive event handling + whereever possible.</para> + </sect3> + + <sect3 id="c-uninitialization"> + <title>C API uninitialization</title> + + <para>Uninitialization is performed by + <computeroutput>g_pVBoxFuncs->pfnClientUninitialize().</computeroutput> + If your program can exit from more than one place, it is a good idea + to install this function as an exit handler with Standard C's + <computeroutput>atexit()</computeroutput> just after calling + <computeroutput>g_pVBoxFuncs->pfnClientInitialize()</computeroutput> + , e.g. <screen>#include <stdlib.h> +#include <stdio.h> + +... + +/* + * Make sure g_pVBoxFuncs->pfnClientUninitialize() is called at exit, no + * matter if we return from the initial call to main or call exit() + * somewhere else. Note that atexit registered functions are not + * called upon abnormal termination, i.e. when calling abort() or + * signal(). + */ + +if (atexit(g_pVBoxFuncs->pfnClientUninitialize()) != 0) { + fprintf(stderr, "failed to register g_pVBoxFuncs->pfnClientUninitialize()\n"); + exit(EXIT_FAILURE); +}</screen></para> + + <para>Another idea would be to write your own <computeroutput>void + myexit(int status)</computeroutput> function, calling + <computeroutput>g_pVBoxFuncs->pfnClientUninitialize()</computeroutput> + followed by the real <computeroutput>exit()</computeroutput>, and + use it instead of <computeroutput>exit()</computeroutput> throughout + your program and at the end of + <computeroutput>main.</computeroutput></para> + + <para>If you expect the program to be terminated by a signal (e.g. + user types CTRL-C sending SIGINT) you might want to install a signal + handler setting a flag noting that a signal was sent and then + calling + <computeroutput>g_pVBoxFuncs->pfnClientUninitialize()</computeroutput> + later on, <emphasis>not</emphasis> from the handler itself.</para> + + <para>That said, if a client program forgets to call + <computeroutput>g_pVBoxFuncs->pfnClientUninitialize()</computeroutput> + before it terminates, there is a mechanism in place which will + eventually release references held by the client. On Windows it can + take quite a while, in the order of 6-7 minutes.</para> + </sect3> + + <sect3 id="c-linking"> + <title>Compiling and linking</title> + + <para>A program using the C binding has to open the library during + runtime using the help of glue code provided and as shown in the + example <computeroutput>tstCAPIGlue.c</computeroutput>. + Compilation and linking can be achieved with a makefile fragment + similar to:<screen># Where is the SDK directory? +PATH_SDK = ../../.. +CAPI_INC = -I$(PATH_SDK)/bindings/c/include +ifdef ProgramFiles +PLATFORM_INC = -I$(PATH_SDK)/bindings/mscom/include +PLATFORM_LIB = $(PATH_SDK)/bindings/mscom/lib +else +PLATFORM_INC = -I$(PATH_SDK)/bindings/xpcom/include +PLATFORM_LIB = $(PATH_SDK)/bindings/xpcom/lib +endif +GLUE_DIR = $(PATH_SDK)/bindings/c/glue +GLUE_INC = -I$(GLUE_DIR) + +# Compile Glue Library +VBoxCAPIGlue.o: $(GLUE_DIR)/VBoxCAPIGlue.c + $(CC) $(CFLAGS) $(CAPI_INC) $(PLATFORM_INC) $(GLUE_INC) -o $@ -c $< + +# Compile interface ID list +VirtualBox_i.o: $(PLATFORM_LIB)/VirtualBox_i.c + $(CC) $(CFLAGS) $(CAPI_INC) $(PLATFORM_INC) $(GLUE_INC) -o $@ -c $< + +# Compile program code +program.o: program.c + $(CC) $(CFLAGS) $(CAPI_INC) $(PLATFORM_INC) $(GLUE_INC) -o $@ -c $< + +# Link program. +program: program.o VBoxCAPICGlue.o VirtualBox_i.o + $(CC) -o $@ $^ -ldl -lpthread</screen></para> + </sect3> + + <sect3 id="capi_conversion"> + <title>Conversion of code using legacy C binding</title> + + <para>This section aims to make the task of converting code using + the legacy C binding to the new style a breeze, by pointing out some + key steps.</para> + + <para>One necessary change is adjusting your Makefile to reflect the + different include paths. See above. There are now 3 relevant include + directories, and most of it is pointing to the C binding directory. + The XPCOM include directory is still relevant for platforms where + the XPCOM middleware is used, but most of the include files live + elsewhere now, so it's good to have it last. Additionally the + <computeroutput>VirtualBox_i.c</computeroutput> file needs to be + compiled and linked to the program, it contains the IIDs relevant + for the VirtualBox API, making sure they are not replicated endlessly + if the code refers to them frequently.</para> + + <para>The C API client code should include + <computeroutput>VBoxCAPIGlue.h</computeroutput> instead of + <computeroutput>VBoxXPCOMCGlue.h</computeroutput> or + <computeroutput>VBoxCAPI_v4_3.h</computeroutput>, as this makes sure + the correct macros and internal translations are selected.</para> + + <para>All API method calls (anything mentioning <code>vtbl</code>) + should be rewritten using the convenience macros for calling methods, + as these hide the internal details, are generally easier to use and + shorter to type. You should remove as many as possible + <code>(nsISupports **)</code> or similar typecasts, as the new style + should use the correct type in most places, increasing the type + safety in case of an error in the source code.</para> + + <para>To gloss over the platform differences, API client code should + no longer rely on XPCOM specific interface names such as + <code>nsISupports</code>, <code>nsIException</code> and + <code>nsIEventQueue</code>, and replace them by the platform + independent interface names <code>IUnknown</code> and + <code>IErrorInfo</code> for the first two respectively. Event queue + handling should be replaced by using the platform independent way + described in <xref linkend="c-eventhandling"/>.</para> + + <para>Finally adjust the string and array handling to use the new + helpers, as these make sure the code works without changes with + both COM and XPCOM, which are significantly different in this area. + The code should be double checked if it uses the correct way to + manage memory, and is freeing it only after the last use.</para> + </sect3> + + <sect3 id="xpcom_cbinding"> + <title>Legacy C binding to VirtualBox API for XPCOM</title> + + <note> + <para>This section applies to Linux, Mac OS X and Solaris + hosts only and describes deprecated use of the API from C.</para> + </note> + + <para>Starting with version 2.2, VirtualBox offers a C binding for + its API which works only on platforms using XPCOM. Refer to the + old SDK documentation (included in the SDK packages for version 4.3.6 + or earlier), it still applies unchanged. The fundamental concepts are + similar (but the syntactical details are quite different) to the + newer cross-platform C binding which should be used for all new code, + as the support for the old C binding will go away in a major release + after version 4.3.</para> + </sect3> + </sect2> + </sect1> + </chapter> + + <chapter id="concepts"> + <title>Basic VirtualBox concepts; some examples</title> + + <para>The following explains some basic VirtualBox concepts such as the + VirtualBox object, sessions and how virtual machines are manipulated and + launched using the Main API. The coding examples use a pseudo-code style + closely related to the object-oriented web service (OOWS) for JAX-WS. + Depending on which environment you are using, you will need to adjust the + examples.</para> + + <sect1> + <title>Obtaining basic machine information. Reading attributes</title> + + <para>Any program using the Main API will first need access to the + global VirtualBox object (see + <link linkend="IVirtualBox">IVirtualBox</link>), from which all other + functionality of the API is derived. With the OOWS for JAX-WS, this is + returned from the + <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link> + call.</para> + + <para>To enumerate virtual machines, one would look at the "machines" + array attribute in the VirtualBox object (see + <link linkend="IVirtualBox__machines">IVirtualBox::machines</link>). + This array contains all virtual machines currently registered with the + host, each of them being an instance of + <link linkend="IMachine">IMachine</link>. + From each such instance, one can query additional information, such as + the UUID, the name, memory, operating system and more by looking at the + attributes; see the attributes list in + <link linkend="IMachine">IMachine</link> documentation.</para> + + <para>As mentioned in the preceding chapters, depending on your + programming environment, attributes are mapped to corresponding "get" + and (if the attribute is not read-only) "set" methods. So when the + documentation says that IMachine has a + "<link linkend="IMachine__name">name</link>" attribute, this means you + need to code something + like the following to get the machine's name: + <screen>IMachine machine = ...; +String name = machine.getName();</screen> + Boolean attribute getters can sometimes be called + <computeroutput>isAttribute()</computeroutput> due to JAX-WS naming + conventions.</para> + </sect1> + + <sect1> + <title>Changing machine settings: Sessions</title> + + <para>As said in the previous section, to read a machine's attribute, + one invokes the corresponding "get" method. One would think that to + change settings of a machine, it would suffice to call the corresponding + "set" method -- for example, to set a VM's memory to 1024 MB, one would + call <computeroutput>setMemorySize(1024)</computeroutput>. Try that, and + you will get an error: "The machine is not mutable."</para> + + <para>So unfortunately, things are not that easy. VirtualBox is a + complicated environment in which multiple processes compete for possibly + the same resources, especially machine settings. As a result, machines + must be "locked" before they can either be modified or started. This is + to prevent multiple processes from making conflicting changes to a + machine: it should, for example, not be allowed to change the memory + size of a virtual machine while it is running. (You can't add more + memory to a real computer while it is running either, at least not to an + ordinary PC.) Also, two processes must not change settings at the same + time, or start a machine at the same time.</para> + + <para>These requirements are implemented in the Main API by way of + "sessions", in particular, the <link linkend="ISession">ISession</link> + interface. Each process which talks to + VirtualBox needs its own instance of ISession. In the web service, you + can request the creation of such an object by calling + <link linkend="IWebsessionManager__getSessionObject">IWebsessionManager::getSessionObject()</link>. + More complex management tasks might need multiple instances of ISession, + and each call returns a new one.</para> + + <para>This session object must then be used like a mutex semaphore in + common programming environments. Before you can change machine settings, + you must write-lock the machine by calling + <link linkend="IMachine__lockMachine">IMachine::lockMachine()</link> + with your process's session object.</para> + + <para>After the machine has been locked, the + <link linkend="ISession__machine">ISession::machine</link> attribute + contains a copy of the original IMachine object upon which the session + was opened, but this copy is "mutable": you can invoke "set" methods on + it.</para> + + <para>When done making the changes to the machine, you must call + <link linkend="IMachine__saveSettings">IMachine::saveSettings()</link>, + which will copy the changes you have made from your "mutable" machine + back to the real machine and write them out to the machine settings XML + file. This will make your changes permanent.</para> + + <para>Finally, it is important to always unlock the machine again, by + calling + <link linkend="ISession__unlockMachine">ISession::unlockMachine()</link>. + Otherwise, when the calling process end, the machine will receive the + "aborted" state, which can lead to loss of data.</para> + + <para>So, as an example, the sequence to change a machine's memory to + 1024 MB is something like this:<screen>IWebsessionManager mgr ...; +IVirtualBox vbox = mgr.logon(user, pass); +... +IMachine machine = ...; // read-only machine +ISession session = mgr.getSessionObject(); +machine.lockMachine(session, LockType.Write); // machine is now locked for writing +IMachine mutable = session.getMachine(); // obtain the mutable machine copy +mutable.setMemorySize(1024); +mutable.saveSettings(); // write settings to XML +session.unlockMachine();</screen></para> + </sect1> + + <sect1> + <title>Launching virtual machines</title> + + <para>To launch a virtual machine, you call + <link linkend="IMachine__launchVMProcess">IMachine::launchVMProcess()</link>. + In doing so, the caller instructs the VirtualBox engine to start a new + process with the virtual machine in it, since to the host, each virtual + machine looks like single process, even if it has hundreds of its own + processes inside. (This new VM process in turn obtains a write lock on + the machine, as described above, to prevent conflicting changes from + other processes; this is why opening another session will fail while the + VM is running.)</para> + + <para>Starting a machine looks something like this: + <screen>IWebsessionManager mgr ...; +IVirtualBox vbox = mgr.logon(user, pass); +... +IMachine machine = ...; // read-only machine +ISession session = mgr.getSessionObject(); +IProgress prog = machine.launchVMProcess(session, + "gui", // session type + ""); // possibly environment setting +prog.waitForCompletion(10000); // give the process 10 secs +if (prog.getResultCode() != 0) // check success + System.out.println("Cannot launch VM!")</screen></para> + + <para>The caller's session object can then be used as a sort of remote + control to the VM process that was launched. It contains a "console" + object (see <link linkend="ISession__console">ISession::console</link>) + with which the VM can be paused, + stopped, snapshotted or other things.</para> + </sect1> + + <sect1 id="events"> + <title>VirtualBox events</title> + + <para>In VirtualBox, "events" provide a uniform mechanism to register + for and consume specific events. A VirtualBox client can register an + "event listener" (represented by the + <link linkend="IEventListener">IEventListener</link> interface), which + will then get notified by the server when an event (represented by the + <link linkend="IEvent">IEvent</link> interface) happens.</para> + + <para>The IEvent interface is an abstract parent interface for all + events that can occur in VirtualBox. The actual events that the server + sends out are then of one of the specific subclasses, for example + <link linkend="IMachineStateChangedEvent">IMachineStateChangedEvent</link> + or + <link linkend="IMediumChangedEvent">IMediumChangedEvent</link>.</para> + + <para>As an example, the VirtualBox GUI waits for machine events and can + thus update its display when the machine state changes or machine + settings are modified, even if this happens in another client. This is + how the GUI can automatically refresh its display even if you manipulate + a machine from another client, for example, from VBoxManage.</para> + + <para>To register an event listener to listen to events, use code like + this:<screen>EventSource es = console.getEventSource(); +IEventListener listener = es.createListener(); +VBoxEventType aTypes[] = (VBoxEventType.OnMachineStateChanged); + // list of event types to listen for +es.registerListener(listener, aTypes, false /* active */); + // register passive listener +IEvent ev = es.getEvent(listener, 1000); + // wait up to one second for event to happen +if (ev != null) +{ + // downcast to specific event interface (in this case we have only registered + // for one type, otherwise IEvent::type would tell us) + IMachineStateChangedEvent mcse = IMachineStateChangedEvent.queryInterface(ev); + ... // inspect and do something + es.eventProcessed(listener, ev); +} +... +es.unregisterListener(listener); </screen></para> + + <para>A graphical user interface would probably best start its own + thread to wait for events and then process these in a loop.</para> + + <para>The events mechanism was introduced with VirtualBox 3.3 and + replaces various callback interfaces which were called for each event in + the interface. The callback mechanism was not compatible with scripting + languages, local Java bindings and remote web services as they do not + support callbacks. The new mechanism with events and event listeners + works with all of these.</para> + + <para>To simplify developement of application using events, concept of + event aggregator was introduced. Essentially it's mechanism to aggregate + multiple event sources into single one, and then work with this single + aggregated event source instead of original sources. As an example, one + can evaluate demo recorder in VirtualBox Python shell, shipped with SDK + - it records mouse and keyboard events, represented as separate event + sources. Code is essentially like this:<screen> + listener = console.eventSource.createListener() + agg = console.eventSource.createAggregator([console.keyboard.eventSource, console.mouse.eventSource]) + agg.registerListener(listener, [ctx['global'].constants.VBoxEventType_Any], False) + registered = True + end = time.time() + dur + while time.time() < end: + ev = agg.getEvent(listener, 1000) + processEent(ev) + agg.unregisterListener(listener)</screen> Without using aggregators + consumer have to poll on both sources, or start multiple threads to + block on those sources.</para> + </sect1> + </chapter> + + <chapter id="vboxshell"> + <title>The VirtualBox shell</title> + + <para>VirtualBox comes with an extensible shell, which allows you to + control your virtual machines from the command line. It is also a + nontrivial example of how to use the VirtualBox APIs from Python, for all + three COM/XPCOM/WS styles of the API.</para> + + <para>You can easily extend this shell with your own commands. Create a + subdirectory named + <computeroutput>.config/VirtualBox/shexts</computeroutput> below your home + directory (respectively <computeroutput>.VirtualBox/shexts</computeroutput> + on a Windows system and + <computeroutput>Library/VirtualBox/shexts</computeroutput> on OS X) and put + a Python file implementing your shell extension commands in this directory. + This file must contain an array named + <computeroutput>commands</computeroutput> containing your command + definitions: <screen> + commands = { + 'cmd1': ['Command cmd1 help', cmd1], + 'cmd2': ['Command cmd2 help', cmd2] + } + </screen> For example, to create a command for creating hard drive + images, the following code can be used: <screen> + def createHdd(ctx,args): + # Show some meaningful error message on wrong input + if (len(args) < 3): + print "usage: createHdd sizeM location type" + return 0 + + # Get arguments + size = int(args[1]) + loc = args[2] + if len(args) > 3: + format = args[3] + else: + # And provide some meaningful defaults + format = "vdi" + + # Call VirtualBox API, using context's fields + hdd = ctx['vb'].createMedium(format, loc, ctx['global'].constants.AccessMode_ReadWrite, \ + ctx['global'].constants.DeviceType_HardDisk) + # Access constants using ctx['global'].constants + progress = hdd.createBaseStorage(size, (ctx['global'].constants.MediumVariant_Standard, )) + # use standard progress bar mechanism + ctx['progressBar'](progress) + + + # Report errors + if not hdd.id: + print "cannot create disk (file %s exist?)" %(loc) + return 0 + + # Give user some feedback on success too + print "created HDD with id: %s" %(hdd.id) + + # 0 means continue execution, other values mean exit from the interpreter + return 0 + + commands = { + 'myCreateHDD': ['Create virtual HDD, createHdd size location type', createHdd] + } + </screen> Just store the above text in the file + <computeroutput>createHdd</computeroutput> (or any other meaningful name) + in <computeroutput>.config/VirtualBox/shexts/</computeroutput>. Start the + VirtualBox shell, or just issue the + <computeroutput>reloadExts</computeroutput> command, if the shell is + already running. Your new command will now be available.</para> + </chapter> + + <xi:include href="SDKRef_apiref.xml" xpointer="xpointer(/book/*)" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <chapter id="cloud"> + <title>Working with the Cloud</title> + + <para>VirtualBox supports and goes towards the Oracle tendencies like "move to the Cloud".</para> + + <sect1> + <title>OCI features</title> + <para>VirtualBox supports the Oracle Cloud Infrastructure (OCI). See the interfaces: + <link linkend="ICloudClient">ICloudClient</link>, + <link linkend="ICloudProvider">ICloudProvider</link>, + <link linkend="ICloudProfile">ICloudProfile</link>, + <link linkend="ICloudProviderManager">ICloudProviderManager</link>. + </para> + <para>Each cloud interface has own implementation to support OCI features. There are everal functions in the implementation + which should be explained in details because OCI requires some special data or settings. + </para> + <para> + Also see the enumeration <link linkend="VirtualSystemDescriptionType">VirtualSystemDescriptionType</link> for the possible values. + </para> + </sect1> + + <sect1> + <title>Function ICloudClient::exportVM</title> + <para> + See the <link linkend="ICloudClient__exportVM">ICloudClient::exportVM</link>. + The function exports an existing virtual machine into OCI. The final result of this operation is creation a custom image + from the bootable image of VM. The Id of created image is returned in the parameter "description" (which is + <link linkend="IVirtualSystemDescription">IVirtualSystemDescription</link>) as an entry with the type + VirtualSystemDescriptionType::CloudImageId. The standard steps here are: + <itemizedlist> + <listitem> + <para>Upload VBox image to OCI Object Storage.</para> + </listitem> + <listitem> + <para>Create OCI custom image from the uploaded object.</para> + </listitem> + </itemizedlist> + Parameter "description" must contain all information and settings needed for creation a custom image in OCI. + At least next entries must be presented there before the call: + <itemizedlist> + <listitem> + <para>VirtualSystemDescriptionType::Name - Name of new instance in OCI.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::HardDiskImage - The local path or id of bootable VM image.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudBucket - A cloud bucket name where the exported image is uploaded.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudImageDisplayName - A name which is assigned to a new custom image in the OCI.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudKeepObject - Whether keep or delete an uploaded object after its usage.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudLaunchInstance - Whether launch or not a new instance.</para> + </listitem> + </itemizedlist> + </para> + </sect1> + + <sect1> + <title>Function ICloudClient::launchVM</title> + <para> + See the <link linkend="ICloudClient__launchVM">ICloudClient::launchVM</link>. + The function launches a new instance in OCI with a bootable volume previously created from a custom image in OCI or + as the source may be used an existing bootable volume which shouldn't be attached to any instance. + For launching instance from a custom image use the parameter VirtualSystemDescriptionType::CloudImageId. + For launching instance from a bootable volume use the parameter VirtualSystemDescriptionType::CloudBootVolumeId. + Only one of them must be presented otherwise the error will occur. + The final result of this operation is a running instance. The id of created instance is returned + in the parameter "description" (which is <link linkend="IVirtualSystemDescription">IVirtualSystemDescription</link>) + as an entry with the type VirtualSystemDescriptionType::CloudInstanceId. Parameter "description" must contain all information + and settings needed for creation a new instance in OCI. At least next entries must be presented there before the call: + <itemizedlist> + <listitem> + <para>VirtualSystemDescriptionType::Name - Name of new instance in OCI.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudOCISubnet - OCID of existing subnet in OCI which will be used by the instance.</para> + </listitem> + <listitem> + <para> + Use VirtualSystemDescriptionType::CloudImageId - OCID of custom image used as a bootable image for the instance + or + VirtualSystemDescriptionType::CloudBootVolumeId - OCID of existing and non-attached bootable volume used as a bootable volume for the instance. + </para> + </listitem> + <listitem> + <para>Add VirtualSystemDescriptionType::CloudBootDiskSize - The size of instance bootable volume in GB, + If you use VirtualSystemDescriptionType::CloudImageId.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudInstanceShape - The shape of instance according to OCI documentation, + defines the number of CPUs and RAM memory.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudLaunchInstance - Whether launch or not a new instance.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudDomain - Availability domain in OCI where new instance is created.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudPublicIP - Whether the instance will have a public IP or not.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudPublicSSHKey - Public SSH key which is used to connect to an instance via SSH. + It may be one or more records with the type VirtualSystemDescriptionType::CloudPublicSSHKey in the VirtualSystemDescription. + But at least one should be presented otherwise user won't be able to connect to the instance via SSH. + </para> + </listitem> + </itemizedlist> + </para> + </sect1> + + <sect1> + <title>Function ICloudClient::getInstanceInfo</title> + <para> + See the <link linkend="ICloudClient__getInstanceInfo">ICloudClient::getInstanceInfo</link>. + The function takes an instance id (parameter "uid"), finds the requested instance in OCI and gets back information + about the found instance in the parameter "description" (which is <link linkend="IVirtualSystemDescription">IVirtualSystemDescription</link>) + The entries with next types will be presented in the object: + <itemizedlist> + <listitem> + <para>VirtualSystemDescriptionType::Name - Displayed name of the instance.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudDomain - Availability domain in OCI.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudImageId - Name of custom image used for creation this instance.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudInstanceId - The OCID of the instance.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::OS - Guest OS type of the instance.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudBootDiskSize - Size of instance bootable image.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudInstanceState - The instance state according to OCI documentation.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudInstanceShape - The instance shape according to OCI documentation</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::Memory - RAM memory in GB allocated for the instance.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CPU - Number of virtual CPUs allocated for the instance.</para> + </listitem> + </itemizedlist> + </para> + </sect1> + + <sect1> + <title>Function ICloudClient::importInstance</title> + <para> + See the <link linkend="ICloudClient__importInstance">ICloudClient::importInstance</link>. + The API function imports an existing instance from the OCI to the local host. + The standard steps here are: + <itemizedlist> + <listitem> + <para>Create a custom image from an existing OCI instance.</para> + </listitem> + <listitem> + <para>Export the custom image to OCI object (the object is created in the OCI Object Storage).</para> + </listitem> + <listitem> + <para>Download the OCI object to the local host.</para> + </listitem> + </itemizedlist> + As the result of operation user will have a file with the suffix ".oci" on the local host. This file is a TAR archive which + contains a bootable instance image in QCOW2 format and a JSON file with some metadata related to + the imported instance. The function takes the parameter "description" + (which is <link linkend="IVirtualSystemDescription">IVirtualSystemDescription</link>) + Parameter "description" must contain all information and settings needed for successful operation result. + At least next entries must be presented there before the call: + <itemizedlist> + <listitem> + <para>VirtualSystemDescriptionType::Name is used for the several purposes: + <itemizedlist> + <listitem> + <para>As a custom image name. A custom image is created from an instance.</para> + </listitem> + <listitem> + <para>As OCI object name. An object is a file in OCI Object Storage. The object is created from the custom image.</para> + </listitem> + <listitem> + <para>Name of imported instance on the local host. Because the result of import is a file, the file will have this + name and extension ".oci".</para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudInstanceId - The OCID of the existing instance.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudBucket - a cloud bucket name in OCI Object Storage where created an OCI object + from a custom image. + </para> + </listitem> + </itemizedlist> + </para> + </sect1> + + </chapter> + + <chapter id="hgcm"> + <title>Host-Guest Communication Manager</title> + + <para>The VirtualBox Host-Guest Communication Manager (HGCM) allows a + guest application or a guest driver to call a host shared library. The + following features of VirtualBox are implemented using HGCM: <itemizedlist> + <listitem> + <para>Shared Folders</para> + </listitem> + + <listitem> + <para>Shared Clipboard</para> + </listitem> + + <listitem> + <para>Guest configuration interface</para> + </listitem> + </itemizedlist></para> + + <para>The shared library contains a so called HGCM service. The guest HGCM + clients establish connections to the service to call it. When calling a + HGCM service the client supplies a function code and a number of + parameters for the function.</para> + + <sect1> + <title>Virtual hardware implementation</title> + + <para>HGCM uses the VMM virtual PCI device to exchange data between the + guest and the host. The guest always acts as an initiator of requests. A + request is constructed in the guest physical memory, which must be + locked by the guest. The physical address is passed to the VMM device + using a 32-bit <computeroutput>out edx, eax</computeroutput> + instruction. The physical memory must be allocated below 4GB by 64-bit + guests.</para> + + <para>The host parses the request header and data and queues the request + for a host HGCM service. The guest continues execution and usually waits + on a HGCM event semaphore.</para> + + <para>When the request has been processed by the HGCM service, the VMM + device sets the completion flag in the request header, sets the HGCM + event and raises an IRQ for the guest. The IRQ handler signals the HGCM + event semaphore and all HGCM callers check the completion flag in the + corresponding request header. If the flag is set, the request is + considered completed.</para> + </sect1> + + <sect1> + <title>Protocol specification</title> + + <para>The HGCM protocol definitions are contained in the + <computeroutput>VBox/VBoxGuest.h</computeroutput></para> + + <sect2> + <title>Request header</title> + + <para>HGCM request structures contains a generic header + (VMMDevHGCMRequestHeader): <table> + <title>HGCM Request Generic Header</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry><emphasis role="bold">Name</emphasis></entry> + + <entry><emphasis role="bold">Description</emphasis></entry> + </row> + + <row> + <entry>size</entry> + + <entry>Size of the entire request.</entry> + </row> + + <row> + <entry>version</entry> + + <entry>Version of the header, must be set to + <computeroutput>0x10001</computeroutput>.</entry> + </row> + + <row> + <entry>type</entry> + + <entry>Type of the request.</entry> + </row> + + <row> + <entry>rc</entry> + + <entry>HGCM return code, which will be set by the VMM + device.</entry> + </row> + + <row> + <entry>reserved1</entry> + + <entry>A reserved field 1.</entry> + </row> + + <row> + <entry>reserved2</entry> + + <entry>A reserved field 2.</entry> + </row> + + <row> + <entry>flags</entry> + + <entry>HGCM flags, set by the VMM device.</entry> + </row> + + <row> + <entry>result</entry> + + <entry>The HGCM result code, set by the VMM device.</entry> + </row> + </tbody> + </tgroup> + </table> <note> + <itemizedlist> + <listitem> + <para>All fields are 32-bit.</para> + </listitem> + + <listitem> + <para>Fields from <computeroutput>size</computeroutput> to + <computeroutput>reserved2</computeroutput> are a standard VMM + device request header, which is used for other interfaces as + well.</para> + </listitem> + </itemizedlist> + </note></para> + + <para>The <emphasis role="bold">type</emphasis> field indicates the + type of the HGCM request: <table> + <title>Request Types</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry><emphasis role="bold">Name (decimal + value)</emphasis></entry> + + <entry><emphasis role="bold">Description</emphasis></entry> + </row> + + <row> + <entry>VMMDevReq_HGCMConnect + (<computeroutput>60</computeroutput>)</entry> + + <entry>Connect to a HGCM service.</entry> + </row> + + <row> + <entry>VMMDevReq_HGCMDisconnect + (<computeroutput>61</computeroutput>)</entry> + + <entry>Disconnect from the service.</entry> + </row> + + <row> + <entry>VMMDevReq_HGCMCall32 + (<computeroutput>62</computeroutput>)</entry> + + <entry>Call a HGCM function using the 32-bit + interface.</entry> + </row> + + <row> + <entry>VMMDevReq_HGCMCall64 + (<computeroutput>63</computeroutput>)</entry> + + <entry>Call a HGCM function using the 64-bit + interface.</entry> + </row> + + <row> + <entry>VMMDevReq_HGCMCancel + (<computeroutput>64</computeroutput>)</entry> + + <entry>Cancel a HGCM request currently being processed by a + host HGCM service.</entry> + </row> + </tbody> + </tgroup> + </table></para> + + <para>The <emphasis role="bold">flags</emphasis> field may contain: + <table> + <title>Flags</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry><emphasis role="bold">Name (hexadecimal + value)</emphasis></entry> + + <entry><emphasis role="bold">Description</emphasis></entry> + </row> + + <row> + <entry>VBOX_HGCM_REQ_DONE + (<computeroutput>0x00000001</computeroutput>)</entry> + + <entry>The request has been processed by the host + service.</entry> + </row> + + <row> + <entry>VBOX_HGCM_REQ_CANCELLED + (<computeroutput>0x00000002</computeroutput>)</entry> + + <entry>This request was cancelled.</entry> + </row> + </tbody> + </tgroup> + </table></para> + </sect2> + + <sect2> + <title>Connect</title> + + <para>The connection request must be issued by the guest HGCM client + before it can call the HGCM service (VMMDevHGCMConnect): <table> + <title>Connect request</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry><emphasis role="bold">Name</emphasis></entry> + + <entry><emphasis role="bold">Description</emphasis></entry> + </row> + + <row> + <entry>header</entry> + + <entry>The generic HGCM request header with type equal to + VMMDevReq_HGCMConnect + (<computeroutput>60</computeroutput>).</entry> + </row> + + <row> + <entry>type</entry> + + <entry>The type of the service location information (32 + bit).</entry> + </row> + + <row> + <entry>location</entry> + + <entry>The service location information (128 bytes).</entry> + </row> + + <row> + <entry>clientId</entry> + + <entry>The client identifier assigned to the connecting + client by the HGCM subsystem (32-bit).</entry> + </row> + </tbody> + </tgroup> + </table> The <emphasis role="bold">type</emphasis> field tells the + HGCM how to look for the requested service: <table> + <title>Location Information Types</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry><emphasis role="bold">Name (hexadecimal + value)</emphasis></entry> + + <entry><emphasis role="bold">Description</emphasis></entry> + </row> + + <row> + <entry>VMMDevHGCMLoc_LocalHost + (<computeroutput>0x1</computeroutput>)</entry> + + <entry>The requested service is a shared library located on + the host and the location information contains the library + name.</entry> + </row> + + <row> + <entry>VMMDevHGCMLoc_LocalHost_Existing + (<computeroutput>0x2</computeroutput>)</entry> + + <entry>The requested service is a preloaded one and the + location information contains the service name.</entry> + </row> + </tbody> + </tgroup> + </table> <note> + <para>Currently preloaded HGCM services are hard-coded in + VirtualBox: <itemizedlist> + <listitem> + <para>VBoxSharedFolders</para> + </listitem> + + <listitem> + <para>VBoxSharedClipboard</para> + </listitem> + + <listitem> + <para>VBoxGuestPropSvc</para> + </listitem> + + <listitem> + <para>VBoxSharedOpenGL</para> + </listitem> + </itemizedlist></para> + </note> There is no difference between both types of HGCM services, + only the location mechanism is different.</para> + + <para>The client identifier is returned by the host and must be used + in all subsequent requests by the client.</para> + </sect2> + + <sect2> + <title>Disconnect</title> + + <para>This request disconnects the client and makes the client + identifier invalid (VMMDevHGCMDisconnect): <table> + <title>Disconnect request</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry><emphasis role="bold">Name</emphasis></entry> + + <entry><emphasis role="bold">Description</emphasis></entry> + </row> + + <row> + <entry>header</entry> + + <entry>The generic HGCM request header with type equal to + VMMDevReq_HGCMDisconnect + (<computeroutput>61</computeroutput>).</entry> + </row> + + <row> + <entry>clientId</entry> + + <entry>The client identifier previously returned by the + connect request (32-bit).</entry> + </row> + </tbody> + </tgroup> + </table></para> + </sect2> + + <sect2> + <title>Call32 and Call64</title> + + <para>Calls the HGCM service entry point (VMMDevHGCMCall) using 32-bit + or 64-bit addresses: <table> + <title>Call request</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry><emphasis role="bold">Name</emphasis></entry> + + <entry><emphasis role="bold">Description</emphasis></entry> + </row> + + <row> + <entry>header</entry> + + <entry>The generic HGCM request header with type equal to + either VMMDevReq_HGCMCall32 + (<computeroutput>62</computeroutput>) or + VMMDevReq_HGCMCall64 + (<computeroutput>63</computeroutput>).</entry> + </row> + + <row> + <entry>clientId</entry> + + <entry>The client identifier previously returned by the + connect request (32-bit).</entry> + </row> + + <row> + <entry>function</entry> + + <entry>The function code to be processed by the service (32 + bit).</entry> + </row> + + <row> + <entry>cParms</entry> + + <entry>The number of following parameters (32-bit). This + value is 0 if the function requires no parameters.</entry> + </row> + + <row> + <entry>parms</entry> + + <entry>An array of parameter description structures + (HGCMFunctionParameter32 or + HGCMFunctionParameter64).</entry> + </row> + </tbody> + </tgroup> + </table></para> + + <para>The 32-bit parameter description (HGCMFunctionParameter32) + consists of 32-bit type field and 8 bytes of an opaque value, so 12 + bytes in total. The 64-bit variant (HGCMFunctionParameter64) consists + of the type and 12 bytes of a value, so 16 bytes in total.</para> + + <para><table> + <title>Parameter types</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry><emphasis role="bold">Type</emphasis></entry> + + <entry><emphasis role="bold">Format of the + value</emphasis></entry> + </row> + + <row> + <entry>VMMDevHGCMParmType_32bit (1)</entry> + + <entry>A 32-bit value.</entry> + </row> + + <row> + <entry>VMMDevHGCMParmType_64bit (2)</entry> + + <entry>A 64-bit value.</entry> + </row> + + <row> + <entry>VMMDevHGCMParmType_PhysAddr (3)</entry> + + <entry>A 32-bit size followed by a 32-bit or 64-bit guest + physical address.</entry> + </row> + + <row> + <entry>VMMDevHGCMParmType_LinAddr (4)</entry> + + <entry>A 32-bit size followed by a 32-bit or 64-bit guest + linear address. The buffer is used both for guest to host + and for host to guest data.</entry> + </row> + + <row> + <entry>VMMDevHGCMParmType_LinAddr_In (5)</entry> + + <entry>Same as VMMDevHGCMParmType_LinAddr but the buffer is + used only for host to guest data.</entry> + </row> + + <row> + <entry>VMMDevHGCMParmType_LinAddr_Out (6)</entry> + + <entry>Same as VMMDevHGCMParmType_LinAddr but the buffer is + used only for guest to host data.</entry> + </row> + + <row> + <entry>VMMDevHGCMParmType_LinAddr_Locked (7)</entry> + + <entry>Same as VMMDevHGCMParmType_LinAddr but the buffer is + already locked by the guest.</entry> + </row> + + <row> + <entry>VMMDevHGCMParmType_LinAddr_Locked_In (1)</entry> + + <entry>Same as VMMDevHGCMParmType_LinAddr_In but the buffer + is already locked by the guest.</entry> + </row> + + <row> + <entry>VMMDevHGCMParmType_LinAddr_Locked_Out (1)</entry> + + <entry>Same as VMMDevHGCMParmType_LinAddr_Out but the buffer + is already locked by the guest.</entry> + </row> + </tbody> + </tgroup> + </table></para> + + <para>The</para> + </sect2> + + <sect2> + <title>Cancel</title> + + <para>This request cancels a call request (VMMDevHGCMCancel): <table> + <title>Cancel request</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry><emphasis role="bold">Name</emphasis></entry> + + <entry><emphasis role="bold">Description</emphasis></entry> + </row> + + <row> + <entry>header</entry> + + <entry>The generic HGCM request header with type equal to + VMMDevReq_HGCMCancel + (<computeroutput>64</computeroutput>).</entry> + </row> + </tbody> + </tgroup> + </table></para> + </sect2> + </sect1> + + <sect1> + <title>Guest software interface</title> + + <para>The guest HGCM clients can call HGCM services from both drivers + and applications.</para> + + <sect2> + <title>The guest driver interface</title> + + <para>The driver interface is implemented in the VirtualBox guest + additions driver (VBoxGuest), which works with the VMM virtual device. + Drivers must use the VBox Guest Library (VBGL), which provides an API + for HGCM clients (<computeroutput>VBox/VBoxGuestLib.h</computeroutput> + and <computeroutput>VBox/VBoxGuest.h</computeroutput>).</para> + + <para><screen> +DECLR0VBGL(int) VbglR0HGCMConnect(VBGLHGCMHANDLE *pHandle, const char *pszServiceName, HGCMCLIENTID *pidClient); + </screen> Connects to the service: <screen> + VBoxGuestHGCMConnectInfo data; + + memset(&data, sizeof(VBoxGuestHGCMConnectInfo)); + + data.result = VINF_SUCCESS; + data.Loc.type = VMMDevHGCMLoc_LocalHost_Existing; + strcpy (data.Loc.u.host.achName, "VBoxSharedFolders"); + + rc = VbglHGCMConnect (&handle, "VBoxSharedFolders"&data); + + if (RT_SUCCESS (rc)) + { + rc = data.result; + } + + if (RT_SUCCESS (rc)) + { + /* Get the assigned client identifier. */ + ulClientID = data.u32ClientID; + } + </screen></para> + + <para><screen> +DECLVBGL(int) VbglHGCMDisconnect (VBGLHGCMHANDLE handle, VBoxGuestHGCMDisconnectInfo *pData); + </screen> Disconnects from the service. <screen> + VBoxGuestHGCMDisconnectInfo data; + + RtlZeroMemory (&data, sizeof (VBoxGuestHGCMDisconnectInfo)); + + data.result = VINF_SUCCESS; + data.u32ClientID = ulClientID; + + rc = VbglHGCMDisconnect (handle, &data); + </screen></para> + + <para><screen> +DECLVBGL(int) VbglHGCMCall (VBGLHGCMHANDLE handle, VBoxGuestHGCMCallInfo *pData, uint32_t cbData); + </screen> Calls a function in the service. <screen> +typedef struct _VBoxSFRead +{ + VBoxGuestHGCMCallInfo callInfo; + + /** pointer, in: SHFLROOT + * Root handle of the mapping which name is queried. + */ + HGCMFunctionParameter root; + + /** value64, in: + * SHFLHANDLE of object to read from. + */ + HGCMFunctionParameter handle; + + /** value64, in: + * Offset to read from. + */ + HGCMFunctionParameter offset; + + /** value64, in/out: + * Bytes to read/How many were read. + */ + HGCMFunctionParameter cb; + + /** pointer, out: + * Buffer to place data to. + */ + HGCMFunctionParameter buffer; + +} VBoxSFRead; + +/** Number of parameters */ +#define SHFL_CPARMS_READ (5) + +... + + VBoxSFRead data; + + /* The call information. */ + data.callInfo.result = VINF_SUCCESS; /* Will be returned by HGCM. */ + data.callInfo.u32ClientID = ulClientID; /* Client identifier. */ + data.callInfo.u32Function = SHFL_FN_READ; /* The function code. */ + data.callInfo.cParms = SHFL_CPARMS_READ; /* Number of parameters. */ + + /* Initialize parameters. */ + data.root.type = VMMDevHGCMParmType_32bit; + data.root.u.value32 = pMap->root; + + data.handle.type = VMMDevHGCMParmType_64bit; + data.handle.u.value64 = hFile; + + data.offset.type = VMMDevHGCMParmType_64bit; + data.offset.u.value64 = offset; + + data.cb.type = VMMDevHGCMParmType_32bit; + data.cb.u.value32 = *pcbBuffer; + + data.buffer.type = VMMDevHGCMParmType_LinAddr_Out; + data.buffer.u.Pointer.size = *pcbBuffer; + data.buffer.u.Pointer.u.linearAddr = (uintptr_t)pBuffer; + + rc = VbglHGCMCall (handle, &data.callInfo, sizeof (data)); + + if (RT_SUCCESS (rc)) + { + rc = data.callInfo.result; + *pcbBuffer = data.cb.u.value32; /* This is returned by the HGCM service. */ + } + </screen></para> + </sect2> + + <sect2> + <title>Guest application interface</title> + + <para>Applications call the VirtualBox Guest Additions driver to + utilize the HGCM interface. There are IOCTL's which correspond to the + <computeroutput>Vbgl*</computeroutput> functions: <itemizedlist> + <listitem> + <para><computeroutput>VBOXGUEST_IOCTL_HGCM_CONNECT</computeroutput></para> + </listitem> + + <listitem> + <para><computeroutput>VBOXGUEST_IOCTL_HGCM_DISCONNECT</computeroutput></para> + </listitem> + + <listitem> + <para><computeroutput>VBOXGUEST_IOCTL_HGCM_CALL</computeroutput></para> + </listitem> + </itemizedlist></para> + + <para>These IOCTL's get the same input buffer as + <computeroutput>VbglHGCM*</computeroutput> functions and the output + buffer has the same format as the input buffer. The same address can + be used as the input and output buffers.</para> + + <para>For example see the guest part of shared clipboard, which runs + as an application and uses the HGCM interface.</para> + </sect2> + </sect1> + + <sect1> + <title>HGCM Service Implementation</title> + + <para>The HGCM service is a shared library with a specific set of entry + points. The library must export the + <computeroutput>VBoxHGCMSvcLoad</computeroutput> entry point: <screen> +extern "C" DECLCALLBACK(DECLEXPORT(int)) VBoxHGCMSvcLoad (VBOXHGCMSVCFNTABLE *ptable) + </screen></para> + + <para>The service must check the + <computeroutput>ptable->cbSize</computeroutput> and + <computeroutput>ptable->u32Version</computeroutput> fields of the + input structure and fill the remaining fields with function pointers of + entry points and the size of the required client buffer size.</para> + + <para>The HGCM service gets a dedicated thread, which calls service + entry points synchronously, that is the service will be called again + only when a previous call has returned. However, the guest calls can be + processed asynchronously. The service must call a completion callback + when the operation is actually completed. The callback can be issued + from another thread as well.</para> + + <para>Service entry points are listed in the + <computeroutput>VBox/hgcmsvc.h</computeroutput> in the + <computeroutput>VBOXHGCMSVCFNTABLE</computeroutput> structure. <table> + <title>Service entry points</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry><emphasis role="bold">Entry</emphasis></entry> + + <entry><emphasis role="bold">Description</emphasis></entry> + </row> + + <row> + <entry>pfnUnload</entry> + + <entry>The service is being unloaded.</entry> + </row> + + <row> + <entry>pfnConnect</entry> + + <entry>A client <computeroutput>u32ClientID</computeroutput> + is connected to the service. The + <computeroutput>pvClient</computeroutput> parameter points to + an allocated memory buffer which can be used by the service to + store the client information.</entry> + </row> + + <row> + <entry>pfnDisconnect</entry> + + <entry>A client is being disconnected.</entry> + </row> + + <row> + <entry>pfnCall</entry> + + <entry>A guest client calls a service function. The + <computeroutput>callHandle</computeroutput> must be used in + the VBOXHGCMSVCHELPERS::pfnCallComplete callback when the call + has been processed.</entry> + </row> + + <row> + <entry>pfnHostCall</entry> + + <entry>Called by the VirtualBox host components to perform + functions which should be not accessible by the guest. Usually + this entry point is used by VirtualBox to configure the + service.</entry> + </row> + + <row> + <entry>pfnSaveState</entry> + + <entry>The VM state is being saved and the service must save + relevant information using the SSM API + (<computeroutput>VBox/ssm.h</computeroutput>).</entry> + </row> + + <row> + <entry>pfnLoadState</entry> + + <entry>The VM is being restored from the saved state and the + service must load the saved information and be able to + continue operations from the saved state.</entry> + </row> + </tbody> + </tgroup> + </table></para> + </sect1> + </chapter> + + <chapter id="rdpweb"> + <title>RDP Web Control</title> + + <para>The VirtualBox <emphasis>RDP Web Control</emphasis> (RDPWeb) + provides remote access to a running VM. RDPWeb is a RDP (Remote Desktop + Protocol) client based on Flash technology and can be used from a Web + browser with a Flash plugin.</para> + + <sect1> + <title>RDPWeb features</title> + + <para>RDPWeb is embedded into a Web page and can connect to VRDP server + in order to displays the VM screen and pass keyboard and mouse events to + the VM.</para> + </sect1> + + <sect1> + <title>RDPWeb reference</title> + + <para>RDPWeb consists of two required components:<itemizedlist> + <listitem> + <para>Flash movie + <computeroutput>RDPClientUI.swf</computeroutput></para> + </listitem> + + <listitem> + <para>JavaScript helpers + <computeroutput>webclient.js</computeroutput></para> + </listitem> + </itemizedlist></para> + + <para>The VirtualBox SDK contains sample HTML code + including:<itemizedlist> + <listitem> + <para>JavaScript library for embedding Flash content + <computeroutput>SWFObject.js</computeroutput></para> + </listitem> + + <listitem> + <para>Sample HTML page + <computeroutput>webclient3.html</computeroutput></para> + </listitem> + </itemizedlist></para> + + <sect2> + <title>RDPWeb functions</title> + + <para><computeroutput>RDPClientUI.swf</computeroutput> and + <computeroutput>webclient.js</computeroutput> work with each other. + JavaScript code is responsible for a proper SWF initialization, + delivering mouse events to the SWF and processing resize requests from + the SWF. On the other hand, the SWF contains a few JavaScript callable + methods, which are used both from + <computeroutput>webclient.js</computeroutput> and the user HTML + page.</para> + + <sect3> + <title>JavaScript functions</title> + + <para><computeroutput>webclient.js</computeroutput> contains helper + functions. In the following table ElementId refers to an HTML + element name or attribute, and Element to the HTML element itself. + HTML code<programlisting> + <div id="FlashRDP"> + </div> +</programlisting> would have ElementId equal to FlashRDP and Element equal to + the div element.</para> + + <para><itemizedlist> + <listitem> + <programlisting>RDPWebClient.embedSWF(SWFFileName, ElementId)</programlisting> + + <para>Uses SWFObject library to replace the HTML element with + the Flash movie.</para> + </listitem> + + <listitem> + <programlisting>RDPWebClient.isRDPWebControlById(ElementId)</programlisting> + + <para>Returns true if the given id refers to a RDPWeb Flash + element.</para> + </listitem> + + <listitem> + <programlisting>RDPWebClient.isRDPWebControlByElement(Element)</programlisting> + + <para>Returns true if the given element is a RDPWeb Flash + element.</para> + </listitem> + + <listitem> + <programlisting>RDPWebClient.getFlashById(ElementId)</programlisting> + + <para>Returns an element, which is referenced by the given id. + This function will try to resolve any element, event if it is + not a Flash movie.</para> + </listitem> + </itemizedlist></para> + </sect3> + + <sect3> + <title>Flash methods callable from JavaScript</title> + + <para><computeroutput>RDPWebClienUI.swf</computeroutput> methods can + be called directly from JavaScript code on a HTML page.</para> + + <itemizedlist> + <listitem> + <para>getProperty(Name)</para> + </listitem> + + <listitem> + <para>setProperty(Name)</para> + </listitem> + + <listitem> + <para>connect()</para> + </listitem> + + <listitem> + <para>disconnect()</para> + </listitem> + + <listitem> + <para>keyboardSendCAD()</para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>Flash JavaScript callbacks</title> + + <para><computeroutput>RDPWebClienUI.swf</computeroutput> calls + JavaScript functions provided by the HTML page.</para> + </sect3> + </sect2> + + <sect2> + <title>Embedding RDPWeb in an HTML page</title> + + <para>It is necessary to include + <computeroutput>webclient.js</computeroutput> helper script. If + SWFObject library is used, the + <computeroutput>swfobject.js</computeroutput> must be also included + and RDPWeb flash content can be embedded to a Web page using dynamic + HTML. The HTML must include a "placeholder", which consists of 2 + <computeroutput>div</computeroutput> elements.</para> + </sect2> + </sect1> + + <sect1> + <title>RDPWeb change log</title> + + <sect2> + <title>Version 1.2.28</title> + + <itemizedlist> + <listitem> + <para><computeroutput>keyboardLayout</computeroutput>, + <computeroutput>keyboardLayouts</computeroutput>, + <computeroutput>UUID</computeroutput> properties.</para> + </listitem> + + <listitem> + <para>Support for German keyboard layout on the client.</para> + </listitem> + + <listitem> + <para>Rebranding to Oracle.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>Version 1.1.26</title> + + <itemizedlist> + <listitem> + <para><computeroutput>webclient.js</computeroutput> is a part of + the distribution package.</para> + </listitem> + + <listitem> + <para><computeroutput>lastError</computeroutput> property.</para> + </listitem> + + <listitem> + <para><computeroutput>keyboardSendScancodes</computeroutput> and + <computeroutput>keyboardSendCAD</computeroutput> methods.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>Version 1.0.24</title> + + <itemizedlist> + <listitem> + <para>Initial release.</para> + </listitem> + </itemizedlist> + </sect2> + </sect1> + </chapter> + + <chapter id="dnd"> + <title>Drag and Drop</title> + + <para>Since VirtualBox 4.2 it's possible to transfer files from host to the + Linux guests by dragging files, directories or text from the host into the + guest's screen. This is called <emphasis>drag and drop + (DnD)</emphasis>.</para> + + <para>In version 5.0 support for Windows guests has been added, as well as + the ability to transfer data the other way around, that is, from the guest + to the host.</para> + + <note><para>Currently only the VirtualBox Manager frontend supports drag and + drop.</para></note> + + <para>This chapter will show how to use the required interfaces provided + by VirtualBox for adding drag and drop functionality to third-party + frontends.</para> + + <sect1> + <title>Basic concepts</title> + + <para>In order to use the interfaces provided by VirtualBox, some basic + concepts needs to be understood first: To successfully initiate a + drag and drop operation at least two sides needs to be involved, a + <emphasis>source</emphasis> and a <emphasis>target</emphasis>:</para> + + <para>The <emphasis>source</emphasis> is the side which provides the + data, e.g. is the origin of data. This data can be stored within the + source directly or can be retrieved on-demand by the source itself. Other + interfaces don't care where the data from this source actually came + from.</para> + + <para>The <emphasis>target</emphasis> on the other hand is the side which + provides the source a visual representation where the user can drop the + data the source offers. This representation can be a window (or just a + certain part of it), for example.</para> + + <para>The source and the target have abstract interfaces called + <link linkend="IDnDSource">IDnDSource</link> and + <link linkend="IDnDTarget">IDnDTarget</link>. VirtualBox also + provides implementations of both interfaces, called + <link linkend="IGuestDnDSource">IGuestDnDSource</link> and + <link linkend="IGuestDnDTarget">IGuestDnDTarget</link>. Both + implementations are also used in the VirtualBox Manager frontend.</para> + </sect1> + + <sect1> + <title>Supported formats</title> + + <para>As the target needs to perform specific actions depending on the + data the source provided, the target first needs to know what type of + data it actually is going to retrieve. It might be that the source offers + data the target cannot (or intentionally does not want to) + support.</para> + + <para>VirtualBox handles those data types by providing so-called + <emphasis>MIME types</emphasis> -- these MIME types were originally + defined in + <ulink url="https://tools.ietf.org/html/rfc2046">RFC 2046</ulink> and + are also called <emphasis>Content-types</emphasis>. + <link linkend="IGuestDnDSource">IGuestDnDSource</link> and + <link linkend="IGuestDnDTarget">IGuestDnDTarget</link> support + the following MIME types by default:<itemizedlist> + <listitem> + <para><emphasis role="bold">text/uri-list</emphasis> - A list of + URIs (Uniform Resource Identifier, see + <ulink url="https://tools.ietf.org/html/rfc3986">RFC 3986</ulink>) + pointing to the file and/or directory paths already transferred + from the source to the target.</para> + </listitem> + <listitem> + <para><emphasis role="bold">text/plain;charset=utf-8</emphasis> and + <emphasis role="bold">UTF8_STRING</emphasis> - text in UTF-8 + format.</para> + </listitem> + <listitem> + <para><emphasis role="bold">text/plain, TEXT</emphasis> + and <emphasis role="bold">STRING</emphasis> - plain ASCII text, + depending on the source's active ANSI page (if any).</para> + </listitem> + </itemizedlist> + </para> + + <para>If, for whatever reason, a certain default format should not be + supported or a new format should be registered, + <link linkend="IDnDSource">IDnDSource</link> and + <link linkend="IDnDTarget">IDnDTarget</link> have methods derived from + <link linkend="IDnDBase">IDnDBase</link> which provide adding, + removing and enumerating specific formats. + <note><para>Registering new or removing default formats on the guest side + currently is not implemented.</para></note></para> + </sect1> + + </chapter> + + <chapter id="vbox-auth"> + <title>VirtualBox external authentication modules</title> + + <para>VirtualBox supports arbitrary external modules to perform + authentication. The module is used when the authentication method is set + to "external" for a particular VM VRDE access and the library was + specified with <computeroutput>VBoxManage setproperty + vrdeauthlibrary</computeroutput>. Web service also use the authentication + module which was specified with <computeroutput>VBoxManage setproperty + websrvauthlibrary</computeroutput>.</para> + + <para>This library will be loaded by the VM or web service process on + demand, i.e. when the first remote desktop connection is made by a client + or when a client that wants to use the web service logs on.</para> + + <para>External authentication is the most flexible as the external handler + can both choose to grant access to everyone (like the "null" + authentication method would) and delegate the request to the guest + authentication component. When delegating the request to the guest + component, the handler will still be called afterwards with the option to + override the result.</para> + + <para>An authentication library is required to implement exactly one entry + point:</para> + + <screen>#include "VBoxAuth.h" + +/** + * Authentication library entry point. + * + * Parameters: + * + * szCaller The name of the component which calls the library (UTF8). + * pUuid Pointer to the UUID of the accessed virtual machine. Can be NULL. + * guestJudgement Result of the guest authentication. + * szUser User name passed in by the client (UTF8). + * szPassword Password passed in by the client (UTF8). + * szDomain Domain passed in by the client (UTF8). + * fLogon Boolean flag. Indicates whether the entry point is called + * for a client logon or the client disconnect. + * clientId Server side unique identifier of the client. + * + * Return code: + * + * AuthResultAccessDenied Client access has been denied. + * AuthResultAccessGranted Client has the right to use the + * virtual machine. + * AuthResultDelegateToGuest Guest operating system must + * authenticate the client and the + * library must be called again with + * the result of the guest + * authentication. + * + * Note: When 'fLogon' is 0, only pszCaller, pUuid and clientId are valid and the return + * code is ignored. + */ +AuthResult AUTHCALL AuthEntry( + const char *szCaller, + PAUTHUUID pUuid, + AuthGuestJudgement guestJudgement, + const char *szUser, + const char *szPassword + const char *szDomain + int fLogon, + unsigned clientId) +{ + /* Process request against your authentication source of choice. */ + // if (authSucceeded(...)) + // return AuthResultAccessGranted; + return AuthResultAccessDenied; +}</screen> + + <para>A note regarding the UUID implementation of the + <computeroutput>pUuid</computeroutput> argument: VirtualBox uses a + consistent binary representation of UUIDs on all platforms. For this + reason the integer fields comprising the UUID are stored as little endian + values. If you want to pass such UUIDs to code which assumes that the + integer fields are big endian (often also called network byte order), you + need to adjust the contents of the UUID to e.g. achieve the same string + representation. The required changes are:<itemizedlist> + <listitem> + <para>reverse the order of byte 0, 1, 2 and 3</para> + </listitem> + + <listitem> + <para>reverse the order of byte 4 and 5</para> + </listitem> + + <listitem> + <para>reverse the order of byte 6 and 7.</para> + </listitem> + </itemizedlist>Using this conversion you will get identical results when + converting the binary UUID to the string representation.</para> + + <para>The <computeroutput>guestJudgement</computeroutput> argument + contains information about the guest authentication status. For the first + call, it is always set to + <computeroutput>AuthGuestNotAsked</computeroutput>. In case the + <computeroutput>AuthEntry</computeroutput> function returns + <computeroutput>AuthResultDelegateToGuest</computeroutput>, a guest + authentication will be attempted and another call to the + <computeroutput>AuthEntry</computeroutput> is made with its result. This + can be either granted / denied or no judgement (the guest component chose + for whatever reason to not make a decision). In case there is a problem + with the guest authentication module (e.g. the Additions are not installed + or not running or the guest did not respond within a timeout), the "not + reacted" status will be returned.</para> + </chapter> + + <chapter id="javaapi"> + <title>Using Java API</title> + + <sect1> + <title>Introduction</title> + + <para>VirtualBox can be controlled by a Java API, both locally + (COM/XPCOM) and from remote (SOAP) clients. As with the Python bindings, + a generic glue layer tries to hide all platform differences, allowing + for source and binary compatibility on different platforms.</para> + </sect1> + + <sect1> + <title>Requirements</title> + + <para>To use the Java bindings, there are certain requirements depending + on the platform. First of all, you need JDK 1.5 (Java 5) or later. Also + please make sure that the version of the VirtualBox API .jar file + exactly matches the version of VirtualBox you use. To avoid confusion, + the VirtualBox API provides versioning in the Java package name, e.g. + the package is named <computeroutput>org.virtualbox_3_2</computeroutput> + for VirtualBox version 3.2. <itemizedlist> + <listitem> + <para><emphasis role="bold">XPCOM</emphasis> - for all platforms, + but Microsoft Windows. A Java bridge based on JavaXPCOM is shipped + with VirtualBox. The classpath must contain + <computeroutput>vboxjxpcom.jar</computeroutput> and the + <computeroutput>vbox.home</computeroutput> property must be set to + location where the VirtualBox binaries are. Please make sure that + the JVM bitness matches bitness of VirtualBox you use as the XPCOM + bridge relies on native libraries.</para> + + <para>Start your application like this: <programlisting> + java -cp vboxjxpcom.jar -Dvbox.home=/opt/virtualbox MyProgram + </programlisting></para> + </listitem> + + <listitem> + <para><emphasis role="bold">COM</emphasis> - for Microsoft + Windows. We rely on <computeroutput>Jacob</computeroutput> - a + generic Java to COM bridge - which has to be installed seperately. + See <ulink + url="http://sourceforge.net/projects/jacob-project/">http://sourceforge.net/projects/jacob-project/</ulink> + for installation instructions. Also, the VirtualBox provided + <computeroutput>vboxjmscom.jar</computeroutput> must be in the + class path.</para> + + <para>Start your application like this: + <programlisting>java -cp vboxjmscom.jar;c:\jacob\jacob.jar -Djava.library.path=c:\jacob MyProgram</programlisting></para> + </listitem> + + <listitem> + <para><emphasis role="bold">SOAP</emphasis> - all platforms. Java + 6 is required, as it comes with builtin support for SOAP via the + JAX-WS library. Also, the VirtualBox provided + <computeroutput>vbojws.jar</computeroutput> must be in the class + path. In the SOAP case it's possible to create several + VirtualBoxManager instances to communicate with multiple + VirtualBox hosts.</para> + + <para>Start your application like this: <programlisting> + java -cp vboxjws.jar MyProgram + </programlisting></para> + </listitem> + </itemizedlist></para> + + <para>Exception handling is also generalized by the generic glue layer, + so that all methods could throw + <computeroutput>VBoxException</computeroutput> containing human-readable + text message (see <computeroutput>getMessage()</computeroutput> method) + along with wrapped original exception (see + <computeroutput>getWrapped()</computeroutput> method).</para> + </sect1> + + <sect1> + <title>Example</title> + + <para>This example shows a simple use case of the Java API. Differences + for SOAP vs. local version are minimal, and limited to the connection + setup phase (see <computeroutput>ws</computeroutput> variable). In the + SOAP case it's possible to create several VirtualBoxManager instances to + communicate with multiple VirtualBox hosts. <programlisting> + import org.virtualbox_4_3.*; + .... + VirtualBoxManager mgr = VirtualBoxManager.createInstance(null); + boolean ws = false; // or true, if we need the SOAP version + if (ws) + { + String url = "http://myhost:18034"; + String user = "test"; + String passwd = "test"; + mgr.connect(url, user, passwd); + } + IVirtualBox vbox = mgr.getVBox(); + System.out.println("VirtualBox version: " + vbox.getVersion() + "\n"); + // get first VM name + String m = vbox.getMachines().get(0).getName(); + System.out.println("\nAttempting to start VM '" + m + "'"); + // start it + mgr.startVm(m, null, 7000); + + if (ws) + mgr.disconnect(); + + mgr.cleanup(); + </programlisting> For more a complete example, see + <computeroutput>TestVBox.java</computeroutput>, shipped with the + SDK. It contains exception handling and error printing code, which + is important for reliable larger scale projects.</para> + + <para>It is good practice in long-running API clients to process the + system events every now and then in the main thread (does not work + in other threads). As a rule of thumb it makes sense to process them + every few 100msec to every few seconds). This is done by + calling<programlisting> + mgr.waitForEvents(0); + </programlisting> + This avoids that a large number of system events accumulate, which can + need a significant amount of memory, and as they also play a role in + object cleanup it helps freeing additional memory in a timely manner + which is used by the API implementation itself. Java's garbage collection + approach already needs more memory due to the delayed freeing of memory + used by no longer accessible objects, and not processing the system + events exacerbates the memory usage. The + <computeroutput>TestVBox.java</computeroutput> example code sprinkles + such lines over the code to achieve the desired effect. In multi-threaded + applications it can be called from the main thread periodically. + Sometimes it's possible to use the non-zero timeout variant of the + method, which then waits the specified number of milliseconds for + events, processing them immediately as they arrive. It achieves better + runtime behavior than separate sleeping/processing.</para> + </sect1> + </chapter> + + <chapter> + <title>License information</title> + + <para>The sample code files shipped with the SDK are generally licensed + liberally to make it easy for anyone to use this code for their own + application code.</para> + + <para>The Java files under + <computeroutput>bindings/webservice/java/jax-ws/</computeroutput> (library + files for the object-oriented web service) are, by contrast, licensed + under the GNU Lesser General Public License (LGPL) V2.1.</para> + + <para>See + <computeroutput>sdk/bindings/webservice/java/jax-ws/src/COPYING.LIB</computeroutput> + for the full text of the LGPL 2.1.</para> + + <para>When in doubt, please refer to the individual source code files + shipped with this SDK.</para> + </chapter> + + <chapter> + <title>Main API change log</title> + + <para>Generally, VirtualBox will maintain API compatibility within a major + release; a major release occurs when the first or the second of the three + version components of VirtualBox change (that is, in the x.y.z scheme, a + major release is one where x or y change, but not when only z + changes).</para> + + <para>In other words, updates like those from 2.0.0 to 2.0.2 will not come + with API breakages.</para> + + <para>Migration between major releases most likely will lead to API + breakage, so please make sure you updated code accordingly. The OOWS Java + wrappers enforce that mechanism by putting VirtualBox classes into + version-specific packages such as + <computeroutput>org.virtualbox_2_2</computeroutput>. This approach allows + for connecting to multiple VirtualBox versions simultaneously from the + same Java application.</para> + + <para>The following sections list incompatible changes that the Main API + underwent since the original release of this SDK Reference with VirtualBox + 2.0. A change is deemed "incompatible" only if it breaks existing client + code (e.g. changes in method parameter lists, renamed or removed + interfaces and similar). In other words, the list does not contain new + interfaces, methods or attributes or other changes that do not affect + existing client code.</para> + + <sect1> + <title>Incompatible API changes with version 7.0</title> + + <itemizedlist> + + <listitem><para>The machine's audio adapter has been moved into the new IAudioSettings interface, which in turn + takes care of of all audio settings of a virtual machine. + See <link linkend="IMachine__audioSettings">IMachine::audioSettings</link> and + <link linkend="IAudioSettings">IAudioSettings</link> for more information.</para> + </listitem> + + <listitem><para>The <link linkend="IVirtualBox__openMachine">IVirtualBox::openMachine</link> call now + requires an additional password parameter. If the machine is not encrypted the parameter is ignored.</para> + </listitem> + + <listitem><para>When a new VM is being created, the default audio driver will be now + <link linkend="AudioDriverType__Default">AudioDriverType_Default</link>. This driver + type will automatically choose the best audio driver (backend) for the host OS &VBOX_PRODUCT; + currently is running on.</para> + </listitem> + + <listitem><para>The host update functionality at IHost::update has been refactored into + <link linkend="IHost__updateHost">IHost::updateHost</link>, which in turn uses the new + <link linkend="IHostUpdateAgent">IHostUpdateAgent</link> interface, derived from the new + <link linkend="IUpdateAgent">IUpdateAgent</link> interface.</para> + </listitem> + + <listitem><para><link linkend="IGuestSession__directoryCopyFromGuest">IGuestSession::directoryCopyFromGuest()</link> and + <link linkend="IGuestSession__directoryCopyToGuest">IGuestSession::directoryCopyToGuest()</link> no longer implicitly + copy recursively and follow symbolic links -- for this to continue working, the newly introduced flags + <link linkend="DirectoryCopyFlag__Recursive">DirectoryCopyFlag::Recursive</link> and/or + <link linkend="DirectoryCopyFlag__FollowLinks">DirectoryCopyFlag::FollowLinks</link> have to be used.</para> + </listitem> + + <listitem><para>VBoxEventType_Last has been renamed to <link linkend="VBoxEventType__End">VBoxEventType_End</link> + for consistency.</para></listitem> + + </itemizedlist> + + </sect1> + + <sect1> + <title>Incompatible API changes with version 6.1</title> + + <itemizedlist> + + <listitem><para>Split off the graphics adapter part of + <link linkend="IMachine">IMachine</link> into + <link linkend="IGraphicsAdapter">IGraphicsAdapter</link>. + This moved 5 attributes.</para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1> + <title>Incompatible API changes with version 6.0</title> + + <itemizedlist> + + <listitem><para>Video recording APIs were changed as follows: + <itemizedlist> + <listitem><para>All attributes which were living in <link linkend="IMachine">IMachine</link> before + have been moved to an own, dedicated interface named <link linkend="IRecordingSettings">IRecordingSettings</link>. + This new interface can be accessed via the new <link linkend="IMachine__recordingSettings">IMachine::recordingSettings</link> + attribute. This should emphasize that recording is not limited to video capturing as such.</para> + </listitem> + + <listitem><para>For further flexibility all specific per-VM-screen settings have been moved to a new interface + called <link linkend="IRecordingScreenSettings">IRecordingScreenSettings</link>. Such settings now exist per configured + VM display and can be retrieved via the <link linkend="IRecordingSettings__screens">IRecordingSettings::screens</link> + attribute or the <link linkend="IRecordingSettings__getScreenSettings">IRecordingSettings::getScreenSettings</link> + method. + <note><para>For now all screen settings will share the same settings, e.g. different settings on a per-screen basis + is not implemented yet.</para></note> + </para> + </listitem> + + <listitem><para>The event <computeroutput>IVideoCaptureChangedEvent</computeroutput> was renamed into + <link linkend="IRecordingChangedEvent">IRecordingChangedEvent</link>.</para> + </listitem> + + </itemizedlist> + </para></listitem> + + <listitem><para>Guest Control APIs were changed as follows: + <itemizedlist> + <listitem><para><link linkend="IGuest__createSession">IGuest::createSession()</link>, + <link linkend="IGuestSession__processCreate">IGuestSession::processCreate()</link>, + <link linkend="IGuestSession__processCreateEx">IGuestSession::processCreateEx()</link>, + <link linkend="IGuestSession__directoryOpen">IGuestSession::directoryOpen()</link> and + <link linkend="IGuestSession__fileOpen">IGuestSession::fileOpen()</link> now will + return the new error code VBOX_E_MAXIMUM_REACHED if the limit for the according object + group has been reached.</para> + </listitem> + + <listitem><para>The enumerations FileOpenExFlags, FsObjMoveFlags and DirectoryCopyFlags have + been renamed to <link linkend="FileOpenExFlag">FileOpenExFlag</link>, + <link linkend="FsObjMoveFlag">FsObjMoveFlag</link> and <link linkend="DirectoryCopyFlag">DirectoryCopyFlag</link> + accordingly to match the rest of the API.</para> + </listitem> + + <listitem> + <para>The following methods have been implemented: + <computeroutput>IGuestSession::directoryCopyFromGuest()</computeroutput> and + <computeroutput>IGuestSession::directoryCopyToGuest()</computeroutput>. + </para> + + <para>The following attributes have been implemented: + <computeroutput>IGuestFsObjInfo::accessTime</computeroutput>, + <computeroutput>IGuestFsObjInfo::birthTime</computeroutput>, + <computeroutput>IGuestFsObjInfo::changeTime</computeroutput> and + <computeroutput>IGuestFsObjInfo::modificationTime</computeroutput>. + </para> + + </listitem> + </itemizedlist> + </para></listitem> + + <listitem><para>The webservice version of the <link linkend="ISharedFolder">ISharedFolder</link> + interface was changed from a struct to a managed object. This causes incompatiblities on the + protocol level as the shared folder attributes are not returned in the responses of + <link linkend="IVirtualBox__sharedFolders">IVirtualBox::getSharedFolders</link> and + <link linkend="IMachine__sharedFolders">IMachine::getSharedFolders</link> anymore. They + return object UUIDs instead which need be wrapped by stub objects. The change is not visible when + using the appropriate client bindings from the most recent VirtualBox SDK. + </para></listitem> + + </itemizedlist> + + </sect1> + + <sect1> + <title>Incompatible API changes with version 5.x</title> + + <itemizedlist> + <listitem><para>ProcessCreateFlag::NoProfile has been renamed to + <link linkend="ProcessCreateFlag__Profile">ProcessCreateFlag::Profile</link>, + whereas the semantics also has been changed: ProcessCreateFlag::NoProfile + explicitly <emphasis role="bold">did not</emphasis> utilize the guest user's profile data, + which in turn <link linkend="ProcessCreateFlag__Profile">ProcessCreateFlag::Profile</link> + explicitly <emphasis role="bold">does now</emphasis>.</para> + </listitem> + </itemizedlist> + + </sect1> + + <sect1> + <title>Incompatible API changes with version 5.0</title> + + <itemizedlist> + <listitem> + <para>The methods for saving state, adopting a saved state file, + discarding a saved state, taking a snapshot, restoring + a snapshot and deleting a snapshot have been moved from + <computeroutput>IConsole</computeroutput> to + <computeroutput>IMachine</computeroutput>. This straightens out the + logical placement of methods and was necessary to resolve a + long-standing issue, preventing 32-bit API clients from invoking + those operations in the case where no VM is running. + <itemizedlist> + <listitem><para><link linkend="IMachine__saveState">IMachine::saveState()</link> + replaces + <computeroutput>IConsole::saveState()</computeroutput></para> + </listitem> + <listitem> + <para><link linkend="IMachine__adoptSavedState">IMachine::adoptSavedState()</link> + replaces + <computeroutput>IConsole::adoptSavedState()</computeroutput></para> + </listitem> + <listitem> + <para><link linkend="IMachine__discardSavedState">IMachine::discardSavedState()</link> + replaces + <computeroutput>IConsole::discardSavedState()</computeroutput></para> + </listitem> + <listitem> + <para><link linkend="IMachine__takeSnapshot">IMachine::takeSnapshot()</link> + replaces + <computeroutput>IConsole::takeSnapshot()</computeroutput></para> + </listitem> + <listitem> + <para><link linkend="IMachine__deleteSnapshot">IMachine::deleteSnapshot()</link> + replaces + <computeroutput>IConsole::deleteSnapshot()</computeroutput></para> + </listitem> + <listitem> + <para><link linkend="IMachine__deleteSnapshotAndAllChildren">IMachine::deleteSnapshotAndAllChildren()</link> + replaces + <computeroutput>IConsole::deleteSnapshotAndAllChildren()</computeroutput></para> + </listitem> + <listitem> + <para><link linkend="IMachine__deleteSnapshotRange">IMachine::deleteSnapshotRange()</link> + replaces + <computeroutput>IConsole::deleteSnapshotRange()</computeroutput></para> + </listitem> + <listitem> + <para><link linkend="IMachine__restoreSnapshot">IMachine::restoreSnapshot()</link> + replaces + <computeroutput>IConsole::restoreSnapshot()</computeroutput></para> + </listitem> + </itemizedlist> + Small adjustments to the parameter lists have been made to reduce + the number of API calls when taking online snapshots (no longer + needs explicit pausing), and taking a snapshot also returns now + the snapshot id (useful for finding the right snapshot if there + are non-unique snapshot names).</para> + </listitem> + + <listitem> + <para>Two new machine states have been introduced to allow proper + distinction between saving state and taking a snapshot. + <link linkend="MachineState__Saving">MachineState::Saving</link> + now is used exclusively while the VM's state is being saved, without + any overlaps with snapshot functionality. The new state + <link linkend="MachineState__Snapshotting">MachineState::Snapshotting</link> + is used when an offline snapshot is taken and likewise the new state + <link linkend="MachineState__OnlineSnapshotting">MachineState::OnlineSnapshotting</link> + is used when an online snapshot is taken.</para> + </listitem> + + <listitem> + <para>A new event has been introduced, which signals when a snapshot + has been restored: + <link linkend="ISnapshotRestoredEvent">ISnapshotRestoredEvent</link>. + Previously the event + <link linkend="ISnapshotDeletedEvent">ISnapshotDeletedEvent</link> + was signalled, which isn't logical (but could be distinguished from + actual deletion by the fact that the snapshot was still + there).</para> + </listitem> + + <listitem> + <para>The method + <link linkend="IVirtualBox__createMedium">IVirtualBox::createMedium()</link> + replaces + <computeroutput>VirtualBox::createHardDisk()</computeroutput>. + Adjusting existing code needs adding two parameters with + value <computeroutput>AccessMode_ReadWrite</computeroutput> + and <computeroutput>DeviceType_HardDisk</computeroutput> + respectively. The new method supports creating floppy and + DVD images, and (less obviously) further API functionality + such as cloning floppy images.</para> + </listitem> + + <listitem> + <para>The method + <link linkend="IMachine__getStorageControllerByInstance">IMachine::getStorageControllerByInstance()</link> + now has an additional parameter (first parameter), for specifying the + storage bus which the storage controller must be using. The method + was not useful before, as the instance numbers are only unique for a + specfic storage bus.</para> + </listitem> + + <listitem> + <para>The attribute + <computeroutput>IMachine::sessionType</computeroutput> has been + renamed to + <link linkend="IMachine__sessionName">IMachine::sessionName()</link>. + This cleans up the confusing terminology (as the session type is + something different).</para> + </listitem> + + <listitem> + <para>The attribute + <computeroutput>IMachine::guestPropertyNotificationPatterns</computeroutput> + has been removed. In practice it was not usable because it is too + global and didn't distinguish between API clients.</para> + </listitem> + + <listitem><para>Drag and drop APIs were changed as follows:<itemizedlist> + + <listitem> + <para>Methods for providing host to guest drag and drop + functionality, such as + <computeroutput>IGuest::dragHGEnter</computeroutput>, + <computeroutput>IGuest::dragHGMove()</computeroutput>, + <computeroutput>IGuest::dragHGLeave()</computeroutput>, + <computeroutput>IGuest::dragHGDrop()</computeroutput> and + <computeroutput>IGuest::dragHGPutData()</computeroutput>, + have been moved to an abstract base class called + <link linkend="IDnDTarget">IDnDTarget</link>. + VirtualBox implements this base class in the + <link linkend="IGuestDnDTarget">IGuestDnDTarget</link> + interface. The implementation can be used by using the + <link linkend="IGuest__dnDTarget">IGuest::dnDTarget()</link> + method.</para> + <para>Methods for providing guest to host drag and drop + functionality, such as + <computeroutput>IGuest::dragGHPending()</computeroutput>, + <computeroutput>IGuest::dragGHDropped()</computeroutput> and + <computeroutput>IGuest::dragGHGetData()</computeroutput>, + have been moved to an abstract base class called + <link linkend="IDnDSource">IDnDSource</link>. + VirtualBox implements this base class in the + <link linkend="IGuestDnDSource">IGuestDnDSource</link> + interface. The implementation can be used by using the + <link linkend="IGuest__dnDSource">IGuest::dnDSource()</link> + method.</para> + </listitem> + + <listitem> + <para>The <computeroutput>DragAndDropAction</computeroutput> + enumeration has been renamed to + <link linkend="DnDAction">DnDAction</link>.</para> + </listitem> + + <listitem> + <para>The <computeroutput>DragAndDropMode</computeroutput> + enumeration has been renamed to + <link linkend="DnDMode">DnDMode</link>.</para> + </listitem> + + <listitem> + <para>The attribute + <computeroutput>IMachine::dragAndDropMode</computeroutput> + has been renamed to + <link linkend="IMachine__dnDMode">IMachine::dnDMode()</link>.</para> + </listitem> + + <listitem> + <para>The event + <computeroutput>IDragAndDropModeChangedEvent</computeroutput> + has been renamed to + <link linkend="IDnDModeChangedEvent">IDnDModeChangedEvent</link>.</para> + </listitem> + + </itemizedlist></para> + </listitem> + + <listitem><para>IDisplay and IFramebuffer interfaces were changed to + allow IFramebuffer object to reside in a separate frontend + process:<itemizedlist> + + <listitem><para> + IDisplay::ResizeCompleted() has been removed, because the + IFramebuffer object does not provide the screen memory anymore. + </para></listitem> + + <listitem><para> + IDisplay::SetFramebuffer() has been replaced with + IDisplay::AttachFramebuffer() and IDisplay::DetachFramebuffer(). + </para></listitem> + + <listitem><para> + IDisplay::GetFramebuffer() has been replaced with + IDisplay::QueryFramebuffer(). + </para></listitem> + + <listitem><para> + IDisplay::GetScreenResolution() has a new output parameter + <computeroutput>guestMonitorStatus</computeroutput> + which tells whether the monitor is enabled in the guest. + </para></listitem> + + <listitem><para> + IDisplay::TakeScreenShot() and IDisplay::TakeScreenShotToArray() + have a new parameter + <computeroutput>bitmapFormat</computeroutput>. As a consequence of + this, IDisplay::TakeScreenShotPNGToArray() has been removed. + </para></listitem> + + <listitem><para> + IFramebuffer::RequestResize() has been replaced with + IFramebuffer::NotifyChange(). + </para></listitem> + + <listitem><para> + IFramebuffer::NotifyUpdateImage() added to support IFramebuffer + objects in a different process. + </para></listitem> + + <listitem><para> + IFramebuffer::Lock(), IFramebuffer::Unlock(), + IFramebuffer::Address(), IFramebuffer::UsesGuestVRAM() have been + removed because the IFramebuffer object does not provide the screen + memory anymore. + </para></listitem> + + </itemizedlist></para> + </listitem> + + <listitem><para>IGuestSession, IGuestFile and IGuestProcess interfaces + were changed as follows: + <itemizedlist> + <listitem> + <para>Replaced IGuestSession::directoryQueryInfo and + IGuestSession::fileQueryInfo with a new + <link linkend="IGuestSession__fsObjQueryInfo">IGuestSession::fsObjQueryInfo</link> + method that works on any type of file system object.</para> + </listitem> + <listitem> + <para>Replaced IGuestSession::fileRemove, + IGuestSession::symlinkRemoveDirectory and + IGuestSession::symlinkRemoveFile with a new + <link linkend="IGuestSession__fsObjRemove">IGuestSession::fsObjRemove</link> + method that works on any type of file system object except + directories. (fileRemove also worked on any type of object + too, though that was not the intent of the method.)</para> + </listitem> + <listitem> + <para>Replaced IGuestSession::directoryRename and + IGuestSession::directoryRename with a new + <link linkend="IGuestSession__fsObjRename">IGuestSession::fsObjRename</link> + method that works on any type of file system object. + (directoryRename and fileRename may already have worked for + any kind of object, but that was never the intent of the + methods.)</para> + </listitem> + <listitem> + <para>Replaced the unimplemented IGuestSession::directorySetACL + and IGuestSession::fileSetACL with a new + <link linkend="IGuestSession__fsObjSetACL">IGuestSession::fsObjSetACL</link> + method that works on all type of file system object. Also + added a UNIX-style mode parameter as an alternative to the + ACL.</para> + </listitem> + <listitem> + <para>Replaced IGuestSession::fileRemove, + IGuestSession::symlinkRemoveDirectory and + IGuestSession::symlinkRemoveFile with a new + <link linkend="IGuestSession__fsObjRemove">IGuestSession::fsObjRemove</link> + method that works on any type of file system object except + directories (fileRemove also worked on any type of object, + though that was not the intent of the method.)</para> + </listitem> + <listitem> + <para>Renamed IGuestSession::copyTo to + <link linkend="IGuestSession__fileCopyToGuest">IGuestSession::fileCopyToGuest</link>.</para> + </listitem> + <listitem> + <para>Renamed IGuestSession::copyFrom to + <link linkend="IGuestSession__fileCopyFromGuest">IGuestSession::fileCopyFromGuest</link>.</para> + </listitem> + <listitem> + <para>Renamed the CopyFileFlag enum to + <link linkend="FileCopyFlag">FileCopyFlag</link>.</para> + </listitem> + <listitem> + <para>Renamed the IGuestSession::environment attribute to + <link linkend="IGuestSession__environmentChanges">IGuestSession::environmentChanges</link> + to better reflect what it does.</para> + </listitem> + <listitem> + <para>Changed the + <link linkend="IProcess__environment">IGuestProcess::environment</link> + to a stub returning E_NOTIMPL since it wasn't doing what was + advertised (returned changes, not the actual environment).</para> + </listitem> + <listitem> + <para>Renamed IGuestSession::environmentSet to + <link linkend="IGuestSession__environmentScheduleSet">IGuestSession::environmentScheduleSet</link> + to better reflect what it does.</para> + </listitem> + <listitem> + <para>Renamed IGuestSession::environmentUnset to + <link linkend="IGuestSession__environmentScheduleUnset">IGuestSession::environmentScheduleUnset</link> + to better reflect what it does.</para> + </listitem> + <listitem> + <para>Removed IGuestSession::environmentGet it was only getting + changes while giving the impression it was actual environment + variables, and it did not represent scheduled unset + operations.</para> + </listitem> + <listitem> + <para>Removed IGuestSession::environmentClear as it duplicates + assigning an empty array to the + <link linkend="IGuestSession__environmentChanges">IGuestSession::environmentChanges</link> + (formerly known as IGuestSession::environment).</para> + </listitem> + <listitem> + <para>Changed the + <link linkend="IGuestSession__processCreate">IGuestSession::processCreate</link> + and + <link linkend="IGuestSession__processCreateEx">IGuestSession::processCreateEx</link> + methods to accept arguments starting with argument zero (argv[0]) + instead of argument one (argv[1]). (Not yet implemented on the + guest additions side, so argv[0] will probably be ignored for a + short while.)</para> + </listitem> + + <listitem> + <para>Added a followSymlink parameter to the following methods: + <itemizedlist> + <listitem><para><link linkend="IGuestSession__directoryExists">IGuestSession::directoryExists</link></para></listitem> + <listitem><para><link linkend="IGuestSession__fileExists">IGuestSession::fileExists</link></para></listitem> + <listitem><para><link linkend="IGuestSession__fileQuerySize">IGuestSession::fileQuerySize</link></para></listitem> + </itemizedlist></para> + </listitem> + <listitem> + <para>The parameters to the + <link linkend="IGuestSession__fileOpen">IGuestSession::fileOpen</link> + and + <link linkend="IGuestSession__fileOpenEx">IGuestSession::fileOpenEx</link> + methods were altered:<itemizedlist> + <listitem><para>The openMode string parameter was replaced by + the enum + <link linkend="FileAccessMode">FileAccessMode</link> + and renamed to accessMode.</para></listitem> + <listitem><para>The disposition string parameter was replaced + by the enum + <link linkend="FileOpenAction">FileOpenAction</link> + and renamed to openAction.</para></listitem> + <listitem><para>The unimplemented sharingMode string parameter + was replaced by the enum + <link linkend="FileSharingMode">FileSharingMode</link> + (fileOpenEx only).</para></listitem> + <listitem><para>Added a flags parameter taking a list of + <link linkend="FileOpenExFlag">FileOpenExFlag</link> values + (fileOpenEx only).</para></listitem> + <listitem><para>Removed the offset parameter (fileOpenEx + only).</para></listitem> + </itemizedlist></para> + </listitem> + + <listitem> + <para><link linkend="IFile__seek">IGuestFile::seek</link> now + returns the new offset.</para> + </listitem> + <listitem> + <para>Renamed the FileSeekType enum used by + <link linkend="IFile__seek">IGuestFile::seek</link> + to <link linkend="FileSeekOrigin">FileSeekOrigin</link> and + added the missing End value and renaming the Set to + Begin.</para> + </listitem> + <listitem> + <para>Extended the unimplemented + <link linkend="IFile__setACL">IGuestFile::setACL</link> + method with a UNIX-style mode parameter as an alternative to + the ACL.</para> + </listitem> + <listitem> + <para>Renamed the IFile::openMode attribute to + <link linkend="IFile__accessMode">IFile::accessMode</link> + and change the type from string to + <link linkend="FileAccessMode">FileAccessMode</link> to reflect + the changes to the fileOpen methods.</para> + </listitem> + <listitem> + <para>Renamed the IGuestFile::disposition attribute to + <link linkend="IFile__openAction">IFile::openAction</link> and + change the type from string to + <link linkend="FileOpenAction">FileOpenAction</link> to reflect + the changes to the fileOpen methods.</para> + </listitem> + + <!-- Non-incompatible things worth mentioning (stubbed methods/attrs aren't worth it). --> + <listitem> + <para>Added + <link linkend="IGuestSession__pathStyle">IGuestSession::pathStyle</link> + attribute.</para> + </listitem> + <listitem> + <para>Added + <link linkend="IGuestSession__fsObjExists">IGuestSession::fsObjExists</link> + attribute.</para> + </listitem> + + </itemizedlist> + </para> + </listitem> + + <listitem><para> + IConsole::GetDeviceActivity() returns information about multiple + devices. + </para></listitem> + + <listitem><para> + IMachine::ReadSavedThumbnailToArray() has a new parameter + <computeroutput>bitmapFormat</computeroutput>. As a consequence of + this, IMachine::ReadSavedThumbnailPNGToArray() has been removed. + </para></listitem> + + <listitem><para> + IMachine::QuerySavedScreenshotPNGSize() has been renamed to + IMachine::QuerySavedScreenshotInfo() which also returns + an array of available screenshot formats. + </para></listitem> + + <listitem><para> + IMachine::ReadSavedScreenshotPNGToArray() has been renamed to + IMachine::ReadSavedScreenshotToArray() which has a new parameter + <computeroutput>bitmapFormat</computeroutput>. + </para></listitem> + + <listitem><para> + IMachine::QuerySavedThumbnailSize() has been removed. + </para></listitem> + + <listitem> + <para>The method + <link linkend="IWebsessionManager__getSessionObject">IWebsessionManager::getSessionObject()</link> + now returns a new <link linkend="ISession">ISession</link> instance + for every invocation. This puts the behavior in line with other + binding styles, which never forced the equivalent of establishing + another connection and logging in again to get another + instance.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>Incompatible API changes with version 4.3</title> + + <itemizedlist> + <listitem> + <para>The explicit medium locking methods + <link linkend="IMedium__lockRead">IMedium::lockRead()</link> + and <link linkend="IMedium__lockWrite">IMedium::lockWrite()</link> + have been redesigned. They return a lock token object reference + now, and calling the + <link linkend="IToken__abandon">IToken::abandon()</link> method (or + letting the reference count to this object drop to 0) will unlock + it. This eliminates the rather common problem that an API client + crash left behind locks, and also improves the safety (API clients + can't release locks they didn't obtain).</para> + </listitem> + + <listitem> + <para>The parameter list of + <link linkend="IAppliance__write">IAppliance::write()</link> + has been changed slightly, to allow multiple flags to be + passed.</para> + </listitem> + + <listitem> + <para><computeroutput>IMachine::delete</computeroutput> + has been renamed to + <link linkend="IMachine__deleteConfig">IMachine::deleteConfig()</link>, + to improve API client binding compatibility.</para> + </listitem> + + <listitem> + <para><computeroutput>IMachine::export</computeroutput> + has been renamed to + <link linkend="IMachine__exportTo">IMachine::exportTo()</link>, + to improve API client binding compatibility.</para> + </listitem> + + <listitem> + <para>For + <link linkend="IMachine__launchVMProcess">IMachine::launchVMProcess()</link> + the meaning of the <computeroutput>type</computeroutput> parameter + has changed slightly. Empty string now means that the per-VM or + global default frontend is launched. Most callers of this method + should use the empty string now, unless they really want to override + the default and launch a particular frontend.</para> + </listitem> + + <listitem> + <para>Medium management APIs were changed as follows:<itemizedlist> + + <listitem> + <para>The type of attribute + <link linkend="IMedium__variant">IMedium::variant()</link> + changed from <computeroutput>unsigned long</computeroutput> + to <computeroutput>safe-array MediumVariant</computeroutput>. + It is an array of flags instead of a set of flags which were + stored inside one variable. + </para> + </listitem> + + <listitem> + <para>The parameter list for + <link linkend="IMedium__cloneTo">IMedium::cloneTo()</link> + was modified. The type of parameter variant was changed from + unsigned long to safe-array MediumVariant. + </para> + </listitem> + + <listitem> + <para>The parameter list for + <link linkend="IMedium__createBaseStorage">IMedium::createBaseStorage()</link> + was modified. The type of parameter variant was changed from + unsigned long to safe-array MediumVariant. + </para> + </listitem> + + <listitem> + <para>The parameter list for + <link linkend="IMedium__createDiffStorage">IMedium::createDiffStorage()</link> + was modified. The type of parameter variant was changed from + unsigned long to safe-array MediumVariant. + </para> + </listitem> + + <listitem> + <para>The parameter list for + <link linkend="IMedium__cloneToBase">IMedium::cloneToBase()</link> + was modified. The type of parameter variant was changed from + unsigned long to safe-array MediumVariant. + </para> + </listitem> + </itemizedlist></para> + </listitem> + + <listitem> + <para>The type of attribute + <link linkend="IMediumFormat__capabilities">IMediumFormat::capabilities()</link> + changed from <computeroutput>unsigned long</computeroutput> to + <computeroutput>safe-array MediumFormatCapabilities</computeroutput>. + It is an array of flags instead of a set of flags which were stored + inside one variable. + </para> + </listitem> + + <listitem> + <para>The attribute + <link linkend="IMedium__logicalSize">IMedium::logicalSize()</link> + now returns the logical size of exactly this medium object (whether + it is a base or diff image). The old behavior was no longer + acceptable, as each image can have a different capacity.</para> + </listitem> + + <listitem> + <para>Guest control APIs - such as + <link linkend="IGuest">IGuest</link>, + <link linkend="IGuestSession">IGuestSession</link>, + <link linkend="IGuestProcess">IGuestProcess</link> and so on - now + emit own events to provide clients much finer control and the ability + to write own frontends for guest operations. The event + <link linkend="IGuestSessionEvent">IGuestSessionEvent</link> acts as + an abstract base class for all guest control events. Certain guest + events contain a + <link linkend="IVirtualBoxErrorInfo">IVirtualBoxErrorInfo</link> + member to provide more information in case of an error happened on + the guest side.</para> + </listitem> + + <listitem> + <para>Guest control sessions on the guest started by + <link linkend="IGuest__createSession">IGuest::createSession()</link> + now are dedicated guest processes to provide more safety and + performance for certain operations. Also, the + <link linkend="IGuest__createSession">IGuest::createSession()</link> + call does not wait for the guest session being created anymore due + to the dedicated guest session processes just mentioned. This also + will enable webservice clients to handle guest session creation + more gracefully. To wait for a guest session being started, use the + newly added attribute + <link linkend="IGuestSession__status">IGuestSession::status()</link> + to query the current guest session status.</para> + </listitem> + + <listitem> + <para>The <link linkend="IGuestFile">IGuestFile</link> + APIs are now implemented to provide native guest file access from + the host.</para> + </listitem> + + <listitem> + <para>The parameter list for + <link linkend="IGuest__updateGuestAdditions">IMedium::updateGuestAdditions()</link> + was modified. It now supports specifying optional command line + arguments for the Guest Additions installer performing the actual + update on the guest. + </para> + </listitem> + + <listitem> + <para>A new event + <link linkend="IGuestUserStateChangedEvent">IGuestUserStateChangedEvent</link> + was introduced to provide guest user status updates to the host via + event listeners. To use this event there needs to be at least the 4.3 + Guest Additions installed on the guest. At the moment only the states + "Idle" and "InUse" of the + <link linkend="GuestUserState">GuestUserState</link> enumeration arei + supported on Windows guests, starting at Windows 2000 SP2.</para> + </listitem> + + <listitem> + <para> + The attribute + <link linkend="IGuestSession__protocolVersion">IGuestSession::protocolVersion</link> + was added to provide a convenient way to lookup the guest session's + protocol version it uses to communicate with the installed Guest + Additions on the guest. Older Guest Additions will set the protocol + version to 1, whereas Guest Additions 4.3 will set the protocol + version to 2. This might change in the future as new features + arise.</para> + </listitem> + + <listitem> + <para><computeroutput>IDisplay::getScreenResolution</computeroutput> + has been extended to return the display position in the guest.</para> + </listitem> + + <listitem> + <para> + The <link linkend="IUSBController">IUSBController</link> + class is not a singleton of + <link linkend="IMachine">IMachine</link> anymore but + <link linkend="IMachine">IMachine</link> contains a list of USB + controllers present in the VM. The USB device filter handling was + moved to + <link linkend="IUSBDeviceFilters">IUSBDeviceFilters</link>. + </para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>Incompatible API changes with version 4.2</title> + + <itemizedlist> + <listitem> + <para>Guest control APIs for executing guest processes, working with + guest files or directories have been moved to the newly introduced + <link linkend="IGuestSession">IGuestSession</link> interface which + can be created by calling + <link linkend="IGuest__createSession">IGuest::createSession()</link>.</para> + + <para>A guest session will act as a + guest user's impersonation so that the guest credentials only have to + be provided when creating a new guest session. There can be up to 32 + guest sessions at once per VM, each session serving up to 2048 guest + processes running or files opened.</para> + + <para>Instead of working with process or directory handles before + version 4.2, there now are the dedicated interfaces + <link linkend="IGuestProcess">IGuestProcess</link>, + <link linkend="IGuestDirectory">IGuestDirectory</link> and + <link linkend="IGuestFile">IGuestFile</link>. To retrieve more + information of a file system object the new interface + <link linkend="IGuestFsObjInfo">IGuestFsObjInfo</link> has been + introduced.</para> + + <para>Even though the guest control API was changed it is backwards + compatible so that it can be used with older installed Guest + Additions. However, to use upcoming features like process termination + or waiting for input / output new Guest Additions must be installed + when these features got implemented.</para> + + <para>The following limitations apply: + <itemizedlist> + <listitem><para>The <link linkend="IGuestFile">IGuestFile</link> + interface is not fully implemented yet.</para> + </listitem> + <listitem><para>The symbolic link APIs + <link linkend="IGuestSession__symlinkCreate">IGuestSession::symlinkCreate()</link>, + <link linkend="IGuestSession__symlinkExists">IGuestSession::symlinkExists()</link>, + <link linkend="IGuestSession__symlinkRead">IGuestSession::symlinkRead()</link>, + IGuestSession::symlinkRemoveDirectory() and + IGuestSession::symlinkRemoveFile() are not + implemented yet.</para> + </listitem> + <listitem><para>The directory APIs + <link linkend="IGuestSession__directoryRemove">IGuestSession::directoryRemove()</link>, + <link linkend="IGuestSession__directoryRemoveRecursive">IGuestSession::directoryRemoveRecursive()</link>, + IGuestSession::directoryRename() and + IGuestSession::directorySetACL() are not + implemented yet.</para> + </listitem> + <listitem><para>The temporary file creation API + <link linkend="IGuestSession__fileCreateTemp">IGuestSession::fileCreateTemp()</link> + is not implemented yet.</para> + </listitem> + <listitem><para>Guest process termination via + <link linkend="IProcess__terminate">IProcess::terminate()</link> + is not implemented yet.</para> + </listitem> + <listitem><para>Waiting for guest process output via + <link linkend="ProcessWaitForFlag__StdOut">ProcessWaitForFlag::StdOut</link> + and + <link linkend="ProcessWaitForFlag__StdErr">ProcessWaitForFlag::StdErr</link> + is not implemented yet.</para> + <para>To wait for process output, + <link linkend="IProcess__read">IProcess::read()</link> with + appropriate flags still can be used to periodically check for + new output data to arrive. Note that + <link linkend="ProcessCreateFlag__WaitForStdOut">ProcessCreateFlag::WaitForStdOut</link> + and / or + <link linkend="ProcessCreateFlag__WaitForStdErr">ProcessCreateFlag::WaitForStdErr</link> + need to be specified when creating a guest process via + <link linkend="IGuestSession__processCreate">IGuestSession::processCreate()</link> + or + <link linkend="IGuestSession__processCreateEx">IGuestSession::processCreateEx()</link>.</para> + </listitem> + <listitem> + <para>ACL (Access Control List) handling in general is not + implemented yet.</para> + </listitem> + </itemizedlist> + </para> + </listitem> + + <listitem> + <para>The <link linkend="LockType">LockType</link> + enumeration now has an additional value + <computeroutput>VM</computeroutput> which tells + <link linkend="IMachine__lockMachine">IMachine::lockMachine()</link> + to create a full-blown object structure for running a VM. This was + the previous behavior with <computeroutput>Write</computeroutput>, + which now only creates the minimal object structure to save time and + resources (at the moment the Console object is still created, but all + sub-objects such as Display, Keyboard, Mouse, Guest are not.</para> + </listitem> + + <listitem> + <para>Machines can be put in groups (actually an array of groups). + The primary group affects the default placement of files belonging + to a VM. + <link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link> + and + <link linkend="IVirtualBox__composeMachineFilename">IVirtualBox::composeMachineFilename()</link> + have been adjusted accordingly, the former taking an array of groups + as an additional parameter and the latter taking a group as an + additional parameter. The create option handling has been changed for + those two methods, too.</para> + </listitem> + + <listitem> + <para>The method IVirtualBox::findMedium() has been removed, since + it provides a subset of the functionality of + <link linkend="IVirtualBox__openMedium">IVirtualBox::openMedium()</link>.</para> + </listitem> + + <listitem> + <para>The use of acronyms in API enumeration, interface, attribute + and method names has been made much more consistent, previously they + sometimes were lowercase and sometimes mixed case. They are now + consistently all caps:<table> + <title>Renamed identifiers in VirtualBox 4.2</title> + + <tgroup cols="2" style="verywide"> + <tbody> + <row> + <entry><emphasis role="bold">Old name</emphasis></entry> + + <entry><emphasis role="bold">New name</emphasis></entry> + </row> + <row> + <entry>PointingHidType</entry> + <entry><link linkend="PointingHIDType">PointingHIDType</link></entry> + </row> + <row> + <entry>KeyboardHidType</entry> + <entry><link linkend="KeyboardHIDType">KeyboardHIDType</link></entry> + </row> + <row> + <entry>IPciAddress</entry> + <entry><link linkend="IPCIAddress">IPCIAddress</link></entry> + </row> + <row> + <entry>IPciDeviceAttachment</entry> + <entry><link linkend="IPCIDeviceAttachment">IPCIDeviceAttachment</link></entry> + </row> + <row> + <entry>IMachine::pointingHidType</entry> + <entry><link linkend="IMachine__pointingHIDType">IMachine::pointingHIDType</link></entry> + </row> + <row> + <entry>IMachine::keyboardHidType</entry> + <entry><link linkend="IMachine__keyboardHIDType">IMachine::keyboardHIDType</link></entry> + </row> + <row> + <entry>IMachine::hpetEnabled</entry> + <entry><link linkend="IMachine__HPETEnabled">IMachine::HPETEnabled</link></entry> + </row> + <row> + <entry>IMachine::sessionPid</entry> + <entry><link linkend="IMachine__sessionPID">IMachine::sessionPID</link></entry> + </row> + <row> + <entry>IMachine::ioCacheEnabled</entry> + <entry><link linkend="IMachine__IOCacheEnabled">IMachine::IOCacheEnabled</link></entry> + </row> + <row> + <entry>IMachine::ioCacheSize</entry> + <entry><link linkend="IMachine__IOCacheSize">IMachine::IOCacheSize</link></entry> + </row> + <row> + <entry>IMachine::pciDeviceAssignments</entry> + <entry><link linkend="IMachine__PCIDeviceAssignments">IMachine::PCIDeviceAssignments</link></entry> + </row> + <row> + <entry>IMachine::attachHostPciDevice()</entry> + <entry><link linkend="IMachine__attachHostPCIDevice">IMachine::attachHostPCIDevice</link></entry> + </row> + <row> + <entry>IMachine::detachHostPciDevice()</entry> + <entry><link linkend="IMachine__detachHostPCIDevice">IMachine::detachHostPCIDevice()</link></entry> + </row> + <row> + <entry>IConsole::attachedPciDevices</entry> + <entry><link linkend="IConsole__attachedPCIDevices">IConsole::attachedPCIDevices</link></entry> + </row> + <row> + <entry>IHostNetworkInterface::dhcpEnabled</entry> + <entry><link linkend="IHostNetworkInterface__DHCPEnabled">IHostNetworkInterface::DHCPEnabled</link></entry> + </row> + <row> + <entry>IHostNetworkInterface::enableStaticIpConfig()</entry> + <entry><link linkend="IHostNetworkInterface__enableStaticIPConfig">IHostNetworkInterface::enableStaticIPConfig()</link></entry> + </row> + <row> + <entry>IHostNetworkInterface::enableStaticIpConfigV6()</entry> + <entry><link linkend="IHostNetworkInterface__enableStaticIPConfigV6">IHostNetworkInterface::enableStaticIPConfigV6()</link></entry> + </row> + <row> + <entry>IHostNetworkInterface::enableDynamicIpConfig()</entry> + <entry><link linkend="IHostNetworkInterface__enableDynamicIPConfig">IHostNetworkInterface::enableDynamicIPConfig()</link></entry> + </row> + <row> + <entry>IHostNetworkInterface::dhcpRediscover()</entry> + <entry><link linkend="IHostNetworkInterface__DHCPRediscover">IHostNetworkInterface::DHCPRediscover()</link></entry> + </row> + <row> + <entry>IHost::Acceleration3DAvailable</entry> + <entry><link linkend="IHost__acceleration3DAvailable">IHost::acceleration3DAvailable</link></entry> + </row> + <row> + <entry>IGuestOSType::recommendedPae</entry> + <entry><link linkend="IGuestOSType__recommendedPAE">IGuestOSType::recommendedPAE</link></entry> + </row> + <row> + <entry>IGuestOSType::recommendedDvdStorageController</entry> + <entry><link linkend="IGuestOSType__recommendedDVDStorageController">IGuestOSType::recommendedDVDStorageController</link></entry> + </row> + <row> + <entry>IGuestOSType::recommendedDvdStorageBus</entry> + <entry><link linkend="IGuestOSType__recommendedDVDStorageBus">IGuestOSType::recommendedDVDStorageBus</link></entry> + </row> + <row> + <entry>IGuestOSType::recommendedHdStorageController</entry> + <entry><link linkend="IGuestOSType__recommendedHDStorageController">IGuestOSType::recommendedHDStorageController</link></entry> + </row> + <row> + <entry>IGuestOSType::recommendedHdStorageBus</entry> + <entry><link linkend="IGuestOSType__recommendedHDStorageBus">IGuestOSType::recommendedHDStorageBus</link></entry> + </row> + <row> + <entry>IGuestOSType::recommendedUsbHid</entry> + <entry><link linkend="IGuestOSType__recommendedUSBHID">IGuestOSType::recommendedUSBHID</link></entry> + </row> + <row> + <entry>IGuestOSType::recommendedHpet</entry> + <entry><link linkend="IGuestOSType__recommendedHPET">IGuestOSType::recommendedHPET</link></entry> + </row> + <row> + <entry>IGuestOSType::recommendedUsbTablet</entry> + <entry><link linkend="IGuestOSType__recommendedUSBTablet">IGuestOSType::recommendedUSBTablet</link></entry> + </row> + <row> + <entry>IGuestOSType::recommendedRtcUseUtc</entry> + <entry><link linkend="IGuestOSType__recommendedRTCUseUTC">IGuestOSType::recommendedRTCUseUTC</link></entry> + </row> + <row> + <entry>IGuestOSType::recommendedUsb</entry> + <entry><link linkend="IGuestOSType__recommendedUSB">IGuestOSType::recommendedUSB</link></entry> + </row> + <row> + <entry>INetworkAdapter::natDriver</entry> + <entry><link linkend="INetworkAdapter__NATEngine">INetworkAdapter::NATEngine</link></entry> + </row> + <row> + <entry>IUSBController::enabledEhci</entry> + <entry>IUSBController::enabledEHCI"</entry> + </row> + <row> + <entry>INATEngine::tftpPrefix</entry> + <entry><link linkend="INATEngine__TFTPPrefix">INATEngine::TFTPPrefix</link></entry> + </row> + <row> + <entry>INATEngine::tftpBootFile</entry> + <entry><link linkend="INATEngine__TFTPBootFile">INATEngine::TFTPBootFile</link></entry> + </row> + <row> + <entry>INATEngine::tftpNextServer</entry> + <entry><link linkend="INATEngine__TFTPNextServer">INATEngine::TFTPNextServer</link></entry> + </row> + <row> + <entry>INATEngine::dnsPassDomain</entry> + <entry><link linkend="INATEngine__DNSPassDomain">INATEngine::DNSPassDomain</link></entry> + </row> + <row> + <entry>INATEngine::dnsProxy</entry> + <entry><link linkend="INATEngine__DNSProxy">INATEngine::DNSProxy</link></entry> + </row> + <row> + <entry>INATEngine::dnsUseHostResolver</entry> + <entry><link linkend="INATEngine__DNSUseHostResolver">INATEngine::DNSUseHostResolver</link></entry> + </row> + <row> + <entry>VBoxEventType::OnHostPciDevicePlug</entry> + <entry><link linkend="VBoxEventType__OnHostPCIDevicePlug">VBoxEventType::OnHostPCIDevicePlug</link></entry> + </row> + <row> + <entry>ICPUChangedEvent::cpu</entry> + <entry><link linkend="ICPUChangedEvent__CPU">ICPUChangedEvent::CPU</link></entry> + </row> + <row> + <entry>INATRedirectEvent::hostIp</entry> + <entry><link linkend="INATRedirectEvent__hostIP">INATRedirectEvent::hostIP</link></entry> + </row> + <row> + <entry>INATRedirectEvent::guestIp</entry> + <entry><link linkend="INATRedirectEvent__guestIP">INATRedirectEvent::guestIP</link></entry> + </row> + <row> + <entry>IHostPciDevicePlugEvent</entry> + <entry><link linkend="IHostPCIDevicePlugEvent">IHostPCIDevicePlugEvent</link></entry> + </row> + </tbody> + </tgroup></table></para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>Incompatible API changes with version 4.1</title> + + <itemizedlist> + <listitem> + <para>The method + <link linkend="IAppliance__importMachines">IAppliance::importMachines()</link> + has one more parameter now, which allows to configure the import + process in more detail. + </para> + </listitem> + + <listitem> + <para>The method + <link linkend="IVirtualBox__openMedium">IVirtualBox::openMedium()</link> + has one more parameter now, which allows resolving duplicate medium + UUIDs without the need for external tools.</para> + </listitem> + + <listitem> + <para>The <link linkend="INetworkAdapter">INetworkAdapter</link> + interface has been cleaned up. The various methods to activate an + attachment type have been replaced by the + <link linkend="INetworkAdapter__attachmentType">INetworkAdapter::attachmentType</link> + setter.</para> + <para>Additionally each attachment mode now has its own attribute, + which means that host only networks no longer share the settings with + bridged interfaces.</para> + <para>To allow introducing new network attachment implementations + without making API changes, the concept of a generic network + attachment driver has been introduced, which is configurable through + key/value properties.</para> + </listitem> + + <listitem> + <para>This version introduces the guest facilities concept. A guest + facility either represents a module or feature the guest is running + or offering, which is defined by + <link linkend="AdditionsFacilityType">AdditionsFacilityType</link>. + Each facility is member of a + <link linkend="AdditionsFacilityClass">AdditionsFacilityClass</link> + and has a current status indicated by + <link linkend="AdditionsFacilityStatus">AdditionsFacilityStatus</link>, + together with a timestamp (in ms) of the last status update.</para> + <para>To address the above concept, the following changes were made: + <itemizedlist> + <listitem> + <para> + In the <link linkend="IGuest">IGuest</link> interface, the + following were removed: + <itemizedlist> + <listitem> + <para>the + <computeroutput>supportsSeamless</computeroutput> + attribute;</para> + </listitem> + <listitem> + <para>the + <computeroutput>supportsGraphics</computeroutput> + attribute;</para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + The function + <link linkend="IGuest__getFacilityStatus">IGuest::getFacilityStatus()</link> + was added. It quickly provides a facility's status without + the need to get the facility collection with + <link linkend="IGuest__facilities">IGuest::facilities</link>. + </para> + </listitem> + <listitem> + <para> + The attribute + <link linkend="IGuest__facilities">IGuest::facilities</link> + was added to provide an easy to access collection of all + currently known guest facilities, that is, it contains all + facilies where at least one status update was made since the + guest was started. + </para> + </listitem> + <listitem> + <para> + The interface + <link linkend="IAdditionsFacility">IAdditionsFacility</link> + was added to represent a single facility returned by + <link linkend="IGuest__facilities">IGuest::facilities</link>. + </para> + </listitem> + <listitem> + <para> + <link linkend="AdditionsFacilityStatus">AdditionsFacilityStatus</link> + was added to represent a facility's overall status. + </para> + </listitem> + <listitem> + <para> + <link linkend="AdditionsFacilityType">AdditionsFacilityType</link> and + <link linkend="AdditionsFacilityClass">AdditionsFacilityClass</link> were + added to represent the facility's type and class. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>Incompatible API changes with version 4.0</title> + + <itemizedlist> + <listitem> + <para>A new Java glue layer replacing the previous OOWS JAX-WS + bindings was introduced. The new library allows for uniform code + targeting both local (COM/XPCOM) and remote (SOAP) transports. Now, + instead of <computeroutput>IWebsessionManager</computeroutput>, the + new class <computeroutput>VirtualBoxManager</computeroutput> must be + used. See <xref linkend="javaapi"/> for details.</para> + </listitem> + + <listitem> + <para>The confusingly named and impractical session APIs were + changed. In existing client code, the following changes need to be + made:<itemizedlist> + <listitem> + <para>Replace any + <computeroutput>IVirtualBox::openSession(uuidMachine, + ...)</computeroutput> API call with the machine's + <link linkend="IMachine__lockMachine">IMachine::lockMachine()</link> + call and a + <computeroutput>LockType.Write</computeroutput> argument. The + functionality is unchanged, but instead of "opening a direct + session on a machine" all documentation now refers to + "obtaining a write lock on a machine for the client + session".</para> + </listitem> + + <listitem> + <para>Similarly, replace any + <computeroutput>IVirtualBox::openExistingSession(uuidMachine, + ...)</computeroutput> call with the machine's + <link linkend="IMachine__lockMachine">IMachine::lockMachine()</link> + call and a <computeroutput>LockType.Shared</computeroutput> + argument. Whereas it was previously impossible to connect a + client session to a running VM process in a race-free manner, + the new API will atomically either write-lock the machine for + the current session or establish a remote link to an existing + session. Existing client code which tried calling both + <computeroutput>openSession()</computeroutput> and + <computeroutput>openExistingSession()</computeroutput> can now + use this one call instead.</para> + </listitem> + + <listitem> + <para>Third, replace any + <computeroutput>IVirtualBox::openRemoteSession(uuidMachine, + ...)</computeroutput> call with the machine's + <link linkend="IMachine__launchVMProcess">IMachine::launchVMProcess()</link> + call. The functionality is unchanged.</para> + </listitem> + + <listitem> + <para>The <link linkend="SessionState">SessionState</link> enum + was adjusted accordingly: "Open" is now "Locked", "Closed" is + now "Unlocked", "Closing" is now "Unlocking".</para> + </listitem> + </itemizedlist></para> + </listitem> + + <listitem> + <para>Virtual machines created with VirtualBox 4.0 or later no + longer register their media in the global media registry in the + <computeroutput>VirtualBox.xml</computeroutput> file. Instead, such + machines list all their media in their own machine XML files. As a + result, a number of media-related APIs had to be modified again. + <itemizedlist> + <listitem> + <para>Neither + <computeroutput>IVirtualBox::createHardDisk()</computeroutput> + nor + <link linkend="IVirtualBox__openMedium">IVirtualBox::openMedium()</link> + register media automatically any more.</para> + </listitem> + + <listitem> + <para><link linkend="IMachine__attachDevice">IMachine::attachDevice()</link> + and + <link linkend="IMachine__mountMedium">IMachine::mountMedium()</link> + now take an IMedium object instead of a UUID as an argument. It + is these two calls which add media to a registry now (either a + machine registry for machines created with VirtualBox 4.0 or + later or the global registry otherwise). As a consequence, if a + medium is opened but never attached to a machine, it is no + longer added to any registry any more.</para> + </listitem> + + <listitem> + <para>To reduce code duplication, the APIs + IVirtualBox::findHardDisk(), getHardDisk(), findDVDImage(), + getDVDImage(), findFloppyImage() and getFloppyImage() have all + been merged into IVirtualBox::findMedium(), and + IVirtualBox::openHardDisk(), openDVDImage() and + openFloppyImage() have all been merged into + <link linkend="IVirtualBox__openMedium">IVirtualBox::openMedium()</link>.</para> + </listitem> + + <listitem> + <para>The rare use case of changing the UUID and parent UUID + of a medium previously handled by + <computeroutput>openHardDisk()</computeroutput> is now in a + separate IMedium::setIDs method.</para> + </listitem> + + <listitem> + <para><computeroutput>ISystemProperties::get/setDefaultHardDiskFolder()</computeroutput> + have been removed since disk images are now by default placed + in each machine's folder.</para> + </listitem> + + <listitem> + <para>The + <link linkend="ISystemProperties__infoVDSize">ISystemProperties::infoVDSize</link> + attribute replaces the + <computeroutput>getMaxVDISize()</computeroutput> + API call; this now uses bytes instead of megabytes.</para> + </listitem> + </itemizedlist></para> + </listitem> + + <listitem> + <para>Machine management APIs were enhanced as follows:<itemizedlist> + <listitem> + <para><link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link> + is no longer restricted to creating machines in the default + "Machines" folder, but can now create machines at arbitrary + locations. For this to work, the parameter list had to be + changed.</para> + </listitem> + + <listitem> + <para>The long-deprecated + <computeroutput>IVirtualBox::createLegacyMachine()</computeroutput> + API has been removed.</para> + </listitem> + + <listitem> + <para>To reduce code duplication and for consistency with the + aforementioned media APIs, + <computeroutput>IVirtualBox::getMachine()</computeroutput> has + been merged with + <link linkend="IVirtualBox__findMachine">IVirtualBox::findMachine()</link>, + and + <computeroutput>IMachine::getSnapshot()</computeroutput> has + been merged with + <link linkend="IMachine__findSnapshot">IMachine::findSnapshot()</link>.</para> + </listitem> + + <listitem> + <para><computeroutput>IVirtualBox::unregisterMachine()</computeroutput> + was replaced with + <link linkend="IMachine__unregister">IMachine::unregister()</link> + with additional functionality for cleaning up machine + files.</para> + </listitem> + + <listitem> + <para><computeroutput>IMachine::deleteSettings</computeroutput> + has been replaced by IMachine::delete, which allows specifying + which disk images are to be deleted as part of the deletion, + and because it can take a while it also returns a + <computeroutput>IProgress</computeroutput> object reference, + so that the completion of the asynchronous activities can be + monitored.</para> + </listitem> + + <listitem> + <para><computeroutput>IConsole::forgetSavedState</computeroutput> + has been renamed to + <computeroutput>IConsole::discardSavedState()</computeroutput>.</para> + </listitem> + </itemizedlist></para> + </listitem> + + <listitem> + <para>All event callbacks APIs were replaced with a new, generic + event mechanism that can be used both locally (COM, XPCOM) and + remotely (web services). Also, the new mechanism is usable from + scripting languages and a local Java. See + <link linkend="IEvent">events</link> for details. The new concept + will require changes to all clients that used event callbacks.</para> + </listitem> + + <listitem> + <para><computeroutput>additionsActive()</computeroutput> was replaced + with + <link linkend="IGuest__additionsRunLevel">additionsRunLevel()</link> + and + <link linkend="IGuest__getAdditionsStatus">getAdditionsStatus()</link> + in order to support a more detailed status of the current Guest + Additions loading/readiness state. + <link linkend="IGuest__additionsVersion">IGuest::additionsVersion()</link> + no longer returns the Guest Additions interface version but the + installed Guest Additions version and revision in form of + <computeroutput>3.3.0r12345</computeroutput>.</para> + </listitem> + + <listitem> + <para>To address shared folders auto-mounting support, the following + APIs were extended to require an additional + <computeroutput>automount</computeroutput> parameter: <itemizedlist> + <listitem> + <para><link linkend="IVirtualBox__createSharedFolder">IVirtualBox::createSharedFolder()</link></para> + </listitem> + + <listitem> + <para><link linkend="IMachine__createSharedFolder">IMachine::createSharedFolder()</link></para> + </listitem> + + <listitem> + <para><link linkend="IConsole__createSharedFolder">IConsole::createSharedFolder()</link></para> + </listitem> + </itemizedlist> Also, a new property named + <computeroutput>autoMount</computeroutput> was added to the + <link linkend="ISharedFolder">ISharedFolder</link> + interface.</para> + </listitem> + + <listitem> + <para>The appliance (OVF) APIs were enhanced as + follows:<itemizedlist> + <listitem> + <para><computeroutput>IMachine::export</computeroutput> + received an extra parameter + <computeroutput>location</computeroutput>, which is used to + decide for the disk naming.</para> + </listitem> + + <listitem> + <para><link linkend="IAppliance__write">IAppliance::write()</link> + received an extra parameter + <computeroutput>manifest</computeroutput>, which can suppress + creating the manifest file on export.</para> + </listitem> + + <listitem> + <para><link linkend="IVFSExplorer__entryList">IVFSExplorer::entryList()</link> + received two extra parameters + <computeroutput>sizes</computeroutput> and + <computeroutput>modes</computeroutput>, which contains the + sizes (in bytes) and the file access modes (in octal form) of + the returned files.</para> + </listitem> + </itemizedlist></para> + </listitem> + + <listitem> + <para>Support for remote desktop access to virtual machines has been + cleaned up to allow third party implementations of the remote + desktop server. This is called the VirtualBox Remote Desktop + Extension (VRDE) and can be added to VirtualBox by installing the + corresponding extension package; see the VirtualBox User Manual for + details.</para> + + <para>The following API changes were made to support the VRDE + interface: <itemizedlist> + <listitem> + <para><computeroutput>IVRDPServer</computeroutput> has been + renamed to + <link linkend="IVRDEServer">IVRDEServer</link>.</para> + </listitem> + + <listitem> + <para><computeroutput>IRemoteDisplayInfo</computeroutput> has + been renamed to + <link linkend="IVRDEServerInfo">IVRDEServerInfo</link>.</para> + </listitem> + + <listitem> + <para><link linkend="IMachine__VRDEServer">IMachine::VRDEServer</link> + replaces + <computeroutput>VRDPServer.</computeroutput></para> + </listitem> + + <listitem> + <para><link linkend="IConsole__VRDEServerInfo">IConsole::VRDEServerInfo</link> + replaces + <computeroutput>RemoteDisplayInfo</computeroutput>.</para> + </listitem> + + <listitem> + <para><link linkend="ISystemProperties__VRDEAuthLibrary">ISystemProperties::VRDEAuthLibrary</link> + replaces + <computeroutput>RemoteDisplayAuthLibrary</computeroutput>.</para> + </listitem> + + <listitem> + <para>The following methods have been implemented in + <computeroutput>IVRDEServer</computeroutput> to support + generic VRDE properties: <itemizedlist> + <listitem> + <para><link linkend="IVRDEServer__setVRDEProperty">IVRDEServer::setVRDEProperty</link></para> + </listitem> + + <listitem> + <para><link linkend="IVRDEServer__getVRDEProperty">IVRDEServer::getVRDEProperty</link></para> + </listitem> + + <listitem> + <para><link linkend="IVRDEServer__VRDEProperties">IVRDEServer::VRDEProperties</link></para> + </listitem> + </itemizedlist></para> + + <para>A few implementation-specific attributes of the old + <computeroutput>IVRDPServer</computeroutput> interface have + been removed and replaced with properties: <itemizedlist> + <listitem> + <para><computeroutput>IVRDPServer::Ports</computeroutput> + has been replaced with the + <computeroutput>"TCP/Ports"</computeroutput> property. + The property value is a string, which contains a + comma-separated list of ports or ranges of ports. Use a + dash between two port numbers to specify a range. + Example: + <computeroutput>"5000,5010-5012"</computeroutput></para> + </listitem> + + <listitem> + <para><computeroutput>IVRDPServer::NetAddress</computeroutput> + has been replaced with the + <computeroutput>"TCP/Address"</computeroutput> property. + The property value is an IP address string. Example: + <computeroutput>"127.0.0.1"</computeroutput></para> + </listitem> + + <listitem> + <para><computeroutput>IVRDPServer::VideoChannel</computeroutput> + has been replaced with the + <computeroutput>"VideoChannel/Enabled"</computeroutput> + property. The property value is either + <computeroutput>"true"</computeroutput> or + <computeroutput>"false"</computeroutput></para> + </listitem> + + <listitem> + <para><computeroutput>IVRDPServer::VideoChannelQuality</computeroutput> + has been replaced with the + <computeroutput>"VideoChannel/Quality"</computeroutput> + property. The property value is a string which contain a + decimal number in range 10..100. Invalid values are + ignored and the quality is set to the default value 75. + Example: <computeroutput>"50"</computeroutput></para> + </listitem> + </itemizedlist></para> + </listitem> + </itemizedlist></para> + </listitem> + + <listitem> + <para>The VirtualBox external authentication module interface has + been updated and made more generic. Because of that, + <computeroutput>VRDPAuthType</computeroutput> enumeration has been + renamed to <link linkend="AuthType">AuthType</link>.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>Incompatible API changes with version 3.2</title> + + <itemizedlist> + <listitem> + <para>The following interfaces were renamed for consistency: + <itemizedlist> + <listitem> + <para>IMachine::getCpuProperty() is now + <link linkend="IMachine__getCPUProperty">IMachine::getCPUProperty()</link>;</para> + </listitem> + + <listitem> + <para>IMachine::setCpuProperty() is now + <link linkend="IMachine__setCPUProperty">IMachine::setCPUProperty()</link>;</para> + </listitem> + + <listitem> + <para>IMachine::getCpuIdLeaf() is now + <link linkend="IMachine__getCPUIDLeaf">IMachine::getCPUIDLeaf()</link>;</para> + </listitem> + + <listitem> + <para>IMachine::setCpuIdLeaf() is now + <link linkend="IMachine__setCPUIDLeaf">IMachine::setCPUIDLeaf()</link>;</para> + </listitem> + + <listitem> + <para>IMachine::removeCpuIdLeaf() is now + <link linkend="IMachine__removeCPUIDLeaf">IMachine::removeCPUIDLeaf()</link>;</para> + </listitem> + + <listitem> + <para>IMachine::removeAllCpuIdLeafs() is now + <link linkend="IMachine__removeAllCPUIDLeaves">IMachine::removeAllCPUIDLeaves()</link>;</para> + </listitem> + + <listitem> + <para>the CpuPropertyType enum is now + <link linkend="CPUPropertyType">CPUPropertyType</link>.</para> + </listitem> + + <listitem> + <para>IVirtualBoxCallback::onSnapshotDiscarded() is now + IVirtualBoxCallback::onSnapshotDeleted.</para> + </listitem> + </itemizedlist></para> + </listitem> + + <listitem> + <para>When creating a VM configuration with + <link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link> + it is now possible to ignore existing configuration files which would + previously have caused a failure. For this the + <computeroutput>override</computeroutput> parameter was added.</para> + </listitem> + + <listitem> + <para>Deleting snapshots via + <computeroutput>IConsole::deleteSnapshot()</computeroutput> is now + possible while the associated VM is running in almost all cases. + The API is unchanged, but client code that verifies machine states + to determine whether snapshots can be deleted may need to be + adjusted.</para> + </listitem> + + <listitem> + <para>The IoBackendType enumeration was replaced with a boolean flag + (see + <link linkend="IStorageController__useHostIOCache">IStorageController::useHostIOCache</link>).</para> + </listitem> + + <listitem> + <para>To address multi-monitor support, the following APIs were + extended to require an additional + <computeroutput>screenId</computeroutput> parameter: <itemizedlist> + <listitem> + <para>IMachine::querySavedThumbnailSize()</para> + </listitem> + + <listitem> + <para><link linkend="IMachine__readSavedThumbnailToArray">IMachine::readSavedThumbnailToArray()</link></para> + </listitem> + + <listitem> + <para><link linkend="IMachine__querySavedScreenshotInfo">IMachine::querySavedScreenshotPNGSize()</link></para> + </listitem> + + <listitem> + <para><link linkend="IMachine__readSavedScreenshotToArray">IMachine::readSavedScreenshotPNGToArray()</link></para> + </listitem> + </itemizedlist></para> + </listitem> + + <listitem> + <para>The <computeroutput>shape</computeroutput> parameter of + IConsoleCallback::onMousePointerShapeChange was changed from a + implementation-specific pointer to a safearray, enabling scripting + languages to process pointer shapes.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>Incompatible API changes with version 3.1</title> + + <itemizedlist> + <listitem> + <para>Due to the new flexibility in medium attachments that was + introduced with version 3.1 (in particular, full flexibility with + attaching CD/DVD drives to arbitrary controllers), we seized the + opportunity to rework all interfaces dealing with storage media to + make the API more flexible as well as logical. The + <link linkend="IStorageController">IStorageController</link>, + <link linkend="IMedium">IMedium</link>, + <link linkend="IMediumAttachment">IMediumAttachment</link> and + <link linkend="IMachine">IMachine</link> interfaces were + affected the most. Existing code using them to configure storage and + media needs to be carefully checked.</para> + + <para>All media (hard disks, floppies and CDs/DVDs) are now + uniformly handled through the <link linkend="IMedium">IMedium</link> + interface. The device-specific interfaces + (<code>IHardDisk</code>, <code>IDVDImage</code>, + <code>IHostDVDDrive</code>, <code>IFloppyImage</code> and + <code>IHostFloppyDrive</code>) have been merged into IMedium; CD/DVD + and floppy media no longer need special treatment. The device type + of a medium determines in which context it can be used. Some + functionality was moved to the other storage-related + interfaces.</para> + + <para><code>IMachine::attachHardDisk</code> and similar methods have + been renamed and generalized to deal with any type of drive and + medium. + <link linkend="IMachine__attachDevice">IMachine::attachDevice()</link> + is the API method for adding any drive to a storage controller. The + floppy and DVD/CD drives are no longer handled specially, and that + means you can have more than one of them. As before, drives can only + be changed while the VM is powered off. Mounting (or unmounting) + removable media at runtime is possible with + <link linkend="IMachine__mountMedium">IMachine::mountMedium()</link>.</para> + + <para>Newly created virtual machines have no storage controllers + associated with them. Even the IDE Controller needs to be created + explicitly. The floppy controller is now visible as a separate + controller, with a new storage bus type. For each storage bus type + you can query the device types which can be attached, so that it is + not necessary to hardcode any attachment rules.</para> + + <para>This required matching changes e.g. in the callback interfaces + (the medium specific change notification was replaced by a generic + medium change notification) and removing associated enums (e.g. + <code>DriveState</code>). In many places the incorrect use of the + plural form "media" was replaced by "medium", to improve + consistency.</para> + </listitem> + + <listitem> + <para>Reading the + <link linkend="IMedium__state">IMedium::state</link> attribute no + longer automatically performs an accessibility check; a new method + <link linkend="IMedium__refreshState">IMedium::refreshState()</link> + does this. The attribute only returns the state now.</para> + </listitem> + + <listitem> + <para>There were substantial changes related to snapshots, triggered + by the "branched snapshots" functionality introduced with version + 3.1. IConsole::discardSnapshot was renamed to + <computeroutput>IConsole::deleteSnapshot()</computeroutput>. + IConsole::discardCurrentState and + IConsole::discardCurrentSnapshotAndState were removed; corresponding + new functionality is in + <computeroutput>IConsole::restoreSnapshot()</computeroutput>. + Also, when <computeroutput>IConsole::takeSnapshot()</computeroutput> + is called on a running virtual machine, a live snapshot will be + created. The old behavior was to temporarily pause the virtual + machine while creating an online snapshot.</para> + </listitem> + + <listitem> + <para>The <computeroutput>IVRDPServer</computeroutput>, + <computeroutput>IRemoteDisplayInfo"</computeroutput> and + <computeroutput>IConsoleCallback</computeroutput> interfaces were + changed to reflect VRDP server ability to bind to one of available + ports from a list of ports.</para> + + <para>The <computeroutput>IVRDPServer::port</computeroutput> + attribute has been replaced with + <computeroutput>IVRDPServer::ports</computeroutput>, which is a + comma-separated list of ports or ranges of ports.</para> + + <para>An <computeroutput>IRemoteDisplayInfo::port"</computeroutput> + attribute has been added for querying the actual port VRDP server + listens on.</para> + + <para>An IConsoleCallback::onRemoteDisplayInfoChange() notification + callback has been added.</para> + </listitem> + + <listitem> + <para>The parameter lists for the following functions were + modified:<itemizedlist> + <listitem> + <para><link linkend="IHost__removeHostOnlyNetworkInterface">IHost::removeHostOnlyNetworkInterface()</link></para> + </listitem> + + <listitem> + <para><link linkend="IHost__removeUSBDeviceFilter">IHost::removeUSBDeviceFilter()</link></para> + </listitem> + </itemizedlist></para> + </listitem> + + <listitem> + <para>In the OOWS bindings for JAX-WS, the behavior of structures + changed: for one, we implemented natural structures field access so + you can just call a "get" method to obtain a field. Secondly, + setters in structures were disabled as they have no expected effect + and were at best misleading.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>Incompatible API changes with version 3.0</title> + + <itemizedlist> + <listitem> + <para>In the object-oriented web service bindings for JAX-WS, proper + inheritance has been introduced for some classes, so explicit + casting is no longer needed to call methods from a parent class. In + particular, IHardDisk and other classes now properly derive from + <link linkend="IMedium">IMedium</link>.</para> + </listitem> + + <listitem> + <para>All object identifiers (machines, snapshots, disks, etc) + switched from GUIDs to strings (now still having string + representation of GUIDs inside). As a result, no particular internal + structure can be assumed for object identifiers; instead, they + should be treated as opaque unique handles. This change mostly + affects Java and C++ programs; for other languages, GUIDs are + transparently converted to strings.</para> + </listitem> + + <listitem> + <para>The uses of NULL strings have been changed greatly. All out + parameters now use empty strings to signal a null value. For in + parameters both the old NULL and empty string is allowed. This + change was necessary to support more client bindings, especially + using the web service API. Many of them either have no special NULL + value or have trouble dealing with it correctly in the respective + library code.</para> + </listitem> + + <listitem> + <para>Accidentally, the <code>TSBool</code> interface still appeared + in 3.0.0, and was removed in 3.0.2. This is an SDK bug, do not use + the SDK for VirtualBox 3.0.0 for developing clients.</para> + </listitem> + + <listitem> + <para>The type of + <link linkend="IVirtualBoxErrorInfo__resultCode">IVirtualBoxErrorInfo::resultCode</link> + changed from + <computeroutput>result</computeroutput> to + <computeroutput>long</computeroutput>.</para> + </listitem> + + <listitem> + <para>The parameter list of IVirtualBox::openHardDisk was + changed.</para> + </listitem> + + <listitem> + <para>The method IConsole::discardSavedState was renamed to + IConsole::forgetSavedState, and a parameter was added.</para> + </listitem> + + <listitem> + <para>The method IConsole::powerDownAsync was renamed to + <link linkend="IConsole__powerDown">IConsole::powerDown</link>, + and the previous method with that name was deleted. So effectively a + parameter was added.</para> + </listitem> + + <listitem> + <para>In the + <link linkend="IFramebuffer">IFramebuffer</link> interface, the + following were removed:<itemizedlist> + <listitem> + <para>the <computeroutput>operationSupported</computeroutput> + attribute;</para> + + <para>(as a result, the + <computeroutput>FramebufferAccelerationOperation</computeroutput> + enum was no longer needed and removed as well);</para> + </listitem> + + <listitem> + <para>the <computeroutput>solidFill()</computeroutput> + method;</para> + </listitem> + + <listitem> + <para>the <computeroutput>copyScreenBits()</computeroutput> + method.</para> + </listitem> + </itemizedlist></para> + </listitem> + + <listitem> + <para>In the <link linkend="IDisplay">IDisplay</link> + interface, the following were removed:<itemizedlist> + <listitem> + <para>the + <computeroutput>setupInternalFramebuffer()</computeroutput> + method;</para> + </listitem> + + <listitem> + <para>the <computeroutput>lockFramebuffer()</computeroutput> + method;</para> + </listitem> + + <listitem> + <para>the <computeroutput>unlockFramebuffer()</computeroutput> + method;</para> + </listitem> + + <listitem> + <para>the + <computeroutput>registerExternalFramebuffer()</computeroutput> + method.</para> + </listitem> + </itemizedlist></para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>Incompatible API changes with version 2.2</title> + + <itemizedlist> + <listitem> + <para>Added explicit version number into JAX-WS Java package names, + such as <computeroutput>org.virtualbox_2_2</computeroutput>, + allowing connect to multiple VirtualBox clients from single Java + application.</para> + </listitem> + + <listitem> + <para>The interfaces having a "2" suffix attached to them with + version 2.1 were renamed again to have that suffix removed. This + time around, this change involves only the name, there are no + functional differences.</para> + + <para>As a result, IDVDImage2 is now IDVDImage; IHardDisk2 is now + IHardDisk; IHardDisk2Attachment is now IHardDiskAttachment.</para> + + <para>Consequentially, all related methods and attributes that had a + "2" suffix have been renamed; for example, IMachine::attachHardDisk2 + now becomes IMachine::attachHardDisk().</para> + </listitem> + + <listitem> + <para>IVirtualBox::openHardDisk has an extra parameter for opening a + disk read/write or read-only.</para> + </listitem> + + <listitem> + <para>The remaining collections were replaced by more performant + safe-arrays. This affects the following collections:</para> + + <itemizedlist> + <listitem> + <para>IGuestOSTypeCollection</para> + </listitem> + + <listitem> + <para>IHostDVDDriveCollection</para> + </listitem> + + <listitem> + <para>IHostFloppyDriveCollection</para> + </listitem> + + <listitem> + <para>IHostUSBDeviceCollection</para> + </listitem> + + <listitem> + <para>IHostUSBDeviceFilterCollection</para> + </listitem> + + <listitem> + <para>IProgressCollection</para> + </listitem> + + <listitem> + <para>ISharedFolderCollection</para> + </listitem> + + <listitem> + <para>ISnapshotCollection</para> + </listitem> + + <listitem> + <para>IUSBDeviceCollection</para> + </listitem> + + <listitem> + <para>IUSBDeviceFilterCollection</para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para>Since "Host Interface Networking" was renamed to "bridged + networking" and host-only networking was introduced, all associated + interfaces needed renaming as well. In detail:</para> + + <itemizedlist> + <listitem> + <para>The HostNetworkInterfaceType enum has been renamed to + <link linkend="HostNetworkInterfaceMediumType">HostNetworkInterfaceMediumType</link></para> + </listitem> + + <listitem> + <para>The IHostNetworkInterface::type attribute has been renamed + to + <link linkend="IHostNetworkInterface__mediumType">IHostNetworkInterface::mediumType</link></para> + </listitem> + + <listitem> + <para>INetworkAdapter::attachToHostInterface() has been renamed + to INetworkAdapter::attachToBridgedInterface</para> + </listitem> + + <listitem> + <para>In the IHost interface, createHostNetworkInterface() has + been renamed to + <link linkend="IHost__createHostOnlyNetworkInterface">createHostOnlyNetworkInterface()</link></para> + </listitem> + + <listitem> + <para>Similarly, removeHostNetworkInterface() has been renamed + to + <link linkend="IHost__removeHostOnlyNetworkInterface">removeHostOnlyNetworkInterface()</link></para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>Incompatible API changes with version 2.1</title> + + <itemizedlist> + <listitem> + <para>With VirtualBox 2.1, error codes were added to many error + infos that give the caller a machine-readable (numeric) feedback in + addition to the error string that has always been available. This is + an ongoing process, and future versions of this SDK reference will + document the error codes for each method call.</para> + </listitem> + + <listitem> + <para>The hard disk and other media interfaces were completely + redesigned. This was necessary to account for the support of VMDK, + VHD and other image types; since backwards compatibility had to be + broken anyway, we seized the moment to redesign the interfaces in a + more logical way.</para> + + <itemizedlist> + <listitem> + <para>Previously, the old IHardDisk interface had several + derivatives called IVirtualDiskImage, IVMDKImage, IVHDImage, + IISCSIHardDisk and ICustomHardDisk for the various disk formats + supported by VirtualBox. The new IHardDisk2 interface that comes + with version 2.1 now supports all hard disk image formats + itself.</para> + </listitem> + + <listitem> + <para>IHardDiskFormat is a new interface to describe the + available back-ends for hard disk images (e.g. VDI, VMDK, VHD or + iSCSI). The IHardDisk2::format attribute can be used to find out + the back-end that is in use for a particular hard disk image. + ISystemProperties::hardDiskFormats[] contains a list of all + back-ends supported by the system. + <link linkend="ISystemProperties__defaultHardDiskFormat">ISystemProperties::defaultHardDiskFormat</link> + contains the default system format.</para> + </listitem> + + <listitem> + <para>In addition, the new + <link linkend="IMedium">IMedium</link> interface is a generic + interface for hard disk, DVD and floppy images that contains the + attributes and methods shared between them. It can be considered + a parent class of the more specific interfaces for those images, + which are now IHardDisk2, IDVDImage2 and IFloppyImage2.</para> + + <para>In each case, the "2" versions of these interfaces replace + the earlier versions that did not have the "2" suffix. + Previously, the IDVDImage and IFloppyImage interfaces were + entirely unrelated to IHardDisk.</para> + </listitem> + + <listitem> + <para>As a result, all parts of the API that previously + referenced IHardDisk, IDVDImage or IFloppyImage or any of the + old subclasses are gone and will have replacements that use + IHardDisk2, IDVDImage2 and IFloppyImage2; see, for example, + IMachine::attachHardDisk2.</para> + </listitem> + + <listitem> + <para>In particular, the IVirtualBox::hardDisks2 array replaces + the earlier IVirtualBox::hardDisks collection.</para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para><link linkend="IGuestOSType">IGuestOSType</link> was + extended to group operating systems into families and for 64-bit + support.</para> + </listitem> + + <listitem> + <para>The + <link linkend="IHostNetworkInterface">IHostNetworkInterface</link> + interface was completely rewritten to account for the changes in how + Host Interface Networking is now implemented in VirtualBox + 2.1.</para> + </listitem> + + <listitem> + <para>The IVirtualBox::machines2[] array replaces the former + IVirtualBox::machines collection.</para> + </listitem> + + <listitem> + <para>Added + <link linkend="IHost__getProcessorFeature">IHost::getProcessorFeature()</link> + and <link linkend="ProcessorFeature">ProcessorFeature</link> + enumeration.</para> + </listitem> + + <listitem> + <para>The parameter list for + <link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link> + was modified.</para> + </listitem> + + <listitem> + <para>Added IMachine::pushGuestProperty.</para> + </listitem> + + <listitem> + <para>New attributes in IMachine: accelerate3DEnabled, + HWVirtExVPIDEnabled, + <computeroutput>IMachine::guestPropertyNotificationPatterns</computeroutput>, + <link linkend="IMachine__CPUCount">CPUCount</link>.</para> + </listitem> + + <listitem> + <para>Added + <link linkend="IConsole__powerUpPaused">IConsole::powerUpPaused()</link> + and + <link linkend="IConsole__getGuestEnteredACPIMode">IConsole::getGuestEnteredACPIMode()</link>.</para> + </listitem> + + <listitem> + <para>Removed ResourceUsage enumeration.</para> + </listitem> + </itemizedlist> + </sect1> + </chapter> +</book> +<!-- vim: set shiftwidth=2 tabstop=2 expandtab: --> diff --git a/doc/manual/en_US/UserManual.xml b/doc/manual/en_US/UserManual.xml new file mode 100644 index 00000000..69131b90 --- /dev/null +++ b/doc/manual/en_US/UserManual.xml @@ -0,0 +1,112 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<book id="VBOXU" lang="en"> + +<!-- VBox bookinfo section --> + + <bookinfo> + + <title>&VBOX_PRODUCT;</title> + + <subtitle>User Manual</subtitle> + + <edition>Version &VBOX_VERSION_STRING;</edition> + + <corpauthor>&VBOX_VENDOR;</corpauthor> + + <address>http://www.virtualbox.org</address> + + <copyright> + + <year>2004-&VBOX_C_YEAR;</year> + + <holder>&VBOX_VENDOR;</holder> + + </copyright> + + </bookinfo> + + <xi:include href="user_Preface.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_Introduction.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_Installation.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_BasicConcepts.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_GuestAdditions.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_Storage.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_Networking.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_Frontends.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_VBoxManage.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_AdvancedTopics.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_Technical.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_VirtualBoxAPI.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_Troubleshooting.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_Security.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_KnownIssues.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_ChangeLog.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_ThirdParty.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_PrivacyPolicy.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_Glossary.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + +</book> diff --git a/doc/manual/en_US/docbook-refentry-link-replacement-xsl-gen.xsl b/doc/manual/en_US/docbook-refentry-link-replacement-xsl-gen.xsl new file mode 100644 index 00000000..032ebfba --- /dev/null +++ b/doc/manual/en_US/docbook-refentry-link-replacement-xsl-gen.xsl @@ -0,0 +1,41 @@ +<?xml version="1.0"?> +<!-- + docbook-refentry-link-replacement-xsl-gen.xsl: + XSLT stylesheet for generate a stylesheet that replaces links + to the user manual in the manpages. +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<xsl:stylesheet + version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:str="http://xsltsl.org/string" + > + + <xsl:import href="../docbook-refentry-link-replacement-xsl-gen.xsl"/> + + <!-- Translated strings --> + <!-- none needed, English is the base language --> + +</xsl:stylesheet> + diff --git a/doc/manual/en_US/images/clone-vm-1.png b/doc/manual/en_US/images/clone-vm-1.png Binary files differnew file mode 100644 index 00000000..f47904a7 --- /dev/null +++ b/doc/manual/en_US/images/clone-vm-1.png diff --git a/doc/manual/en_US/images/clone-vm-2.png b/doc/manual/en_US/images/clone-vm-2.png Binary files differnew file mode 100644 index 00000000..d8e98d1f --- /dev/null +++ b/doc/manual/en_US/images/clone-vm-2.png diff --git a/doc/manual/en_US/images/clone-vm-3.png b/doc/manual/en_US/images/clone-vm-3.png Binary files differnew file mode 100644 index 00000000..62492a60 --- /dev/null +++ b/doc/manual/en_US/images/clone-vm-3.png diff --git a/doc/manual/en_US/images/cloud-profile-manager.png b/doc/manual/en_US/images/cloud-profile-manager.png Binary files differnew file mode 100644 index 00000000..a262d386 --- /dev/null +++ b/doc/manual/en_US/images/cloud-profile-manager.png diff --git a/doc/manual/en_US/images/cloudvm-add.png b/doc/manual/en_US/images/cloudvm-add.png Binary files differnew file mode 100644 index 00000000..33cf7f1e --- /dev/null +++ b/doc/manual/en_US/images/cloudvm-add.png diff --git a/doc/manual/en_US/images/cloudvm-new.png b/doc/manual/en_US/images/cloudvm-new.png Binary files differnew file mode 100644 index 00000000..9f6016d5 --- /dev/null +++ b/doc/manual/en_US/images/cloudvm-new.png diff --git a/doc/manual/en_US/images/cloudvm-oci-group.png b/doc/manual/en_US/images/cloudvm-oci-group.png Binary files differnew file mode 100644 index 00000000..b302f6b2 --- /dev/null +++ b/doc/manual/en_US/images/cloudvm-oci-group.png diff --git a/doc/manual/en_US/images/cloudvm-overview.png b/doc/manual/en_US/images/cloudvm-overview.png Binary files differnew file mode 100644 index 00000000..2d75c642 --- /dev/null +++ b/doc/manual/en_US/images/cloudvm-overview.png diff --git a/doc/manual/en_US/images/create-vm-1.png b/doc/manual/en_US/images/create-vm-1.png Binary files differnew file mode 100644 index 00000000..88b1cbdc --- /dev/null +++ b/doc/manual/en_US/images/create-vm-1.png diff --git a/doc/manual/en_US/images/create-vm-2.png b/doc/manual/en_US/images/create-vm-2.png Binary files differnew file mode 100644 index 00000000..03b16810 --- /dev/null +++ b/doc/manual/en_US/images/create-vm-2.png diff --git a/doc/manual/en_US/images/create-vm-3.png b/doc/manual/en_US/images/create-vm-3.png Binary files differnew file mode 100644 index 00000000..90c35138 --- /dev/null +++ b/doc/manual/en_US/images/create-vm-3.png diff --git a/doc/manual/en_US/images/create-vm-4.png b/doc/manual/en_US/images/create-vm-4.png Binary files differnew file mode 100644 index 00000000..e3599782 --- /dev/null +++ b/doc/manual/en_US/images/create-vm-4.png diff --git a/doc/manual/en_US/images/details-pane.png b/doc/manual/en_US/images/details-pane.png Binary files differnew file mode 100644 index 00000000..f4042a35 --- /dev/null +++ b/doc/manual/en_US/images/details-pane.png diff --git a/doc/manual/en_US/images/dnd-modes.png b/doc/manual/en_US/images/dnd-modes.png Binary files differnew file mode 100644 index 00000000..0ef22d8a --- /dev/null +++ b/doc/manual/en_US/images/dnd-modes.png diff --git a/doc/manual/en_US/images/export-appliance-oci.png b/doc/manual/en_US/images/export-appliance-oci.png Binary files differnew file mode 100644 index 00000000..312e853b --- /dev/null +++ b/doc/manual/en_US/images/export-appliance-oci.png diff --git a/doc/manual/en_US/images/global-tools-menu.png b/doc/manual/en_US/images/global-tools-menu.png Binary files differnew file mode 100644 index 00000000..a1aaa749 --- /dev/null +++ b/doc/manual/en_US/images/global-tools-menu.png diff --git a/doc/manual/en_US/images/guest-fm.png b/doc/manual/en_US/images/guest-fm.png Binary files differnew file mode 100644 index 00000000..fa0528e2 --- /dev/null +++ b/doc/manual/en_US/images/guest-fm.png diff --git a/doc/manual/en_US/images/import-instance.png b/doc/manual/en_US/images/import-instance.png Binary files differnew file mode 100644 index 00000000..8dfb6ed2 --- /dev/null +++ b/doc/manual/en_US/images/import-instance.png diff --git a/doc/manual/en_US/images/log-viewer.png b/doc/manual/en_US/images/log-viewer.png Binary files differnew file mode 100644 index 00000000..dbe4e9cd --- /dev/null +++ b/doc/manual/en_US/images/log-viewer.png diff --git a/doc/manual/en_US/images/machine-tools-menu.png b/doc/manual/en_US/images/machine-tools-menu.png Binary files differnew file mode 100644 index 00000000..9272ecff --- /dev/null +++ b/doc/manual/en_US/images/machine-tools-menu.png diff --git a/doc/manual/en_US/images/ovf-import.png b/doc/manual/en_US/images/ovf-import.png Binary files differnew file mode 100644 index 00000000..b2d6b1b2 --- /dev/null +++ b/doc/manual/en_US/images/ovf-import.png diff --git a/doc/manual/en_US/images/seamless.png b/doc/manual/en_US/images/seamless.png Binary files differnew file mode 100644 index 00000000..7239300d --- /dev/null +++ b/doc/manual/en_US/images/seamless.png diff --git a/doc/manual/en_US/images/session-information.png b/doc/manual/en_US/images/session-information.png Binary files differnew file mode 100644 index 00000000..a4a64611 --- /dev/null +++ b/doc/manual/en_US/images/session-information.png diff --git a/doc/manual/en_US/images/snapshots-1.png b/doc/manual/en_US/images/snapshots-1.png Binary files differnew file mode 100644 index 00000000..91f790f2 --- /dev/null +++ b/doc/manual/en_US/images/snapshots-1.png diff --git a/doc/manual/en_US/images/snapshots-2.png b/doc/manual/en_US/images/snapshots-2.png Binary files differnew file mode 100644 index 00000000..aca79e1e --- /dev/null +++ b/doc/manual/en_US/images/snapshots-2.png diff --git a/doc/manual/en_US/images/softkeybd.png b/doc/manual/en_US/images/softkeybd.png Binary files differnew file mode 100644 index 00000000..545211bf --- /dev/null +++ b/doc/manual/en_US/images/softkeybd.png diff --git a/doc/manual/en_US/images/upload-key.png b/doc/manual/en_US/images/upload-key.png Binary files differnew file mode 100644 index 00000000..cae44e44 --- /dev/null +++ b/doc/manual/en_US/images/upload-key.png diff --git a/doc/manual/en_US/images/vbox-components.png b/doc/manual/en_US/images/vbox-components.png Binary files differnew file mode 100644 index 00000000..ed1326dc --- /dev/null +++ b/doc/manual/en_US/images/vbox-components.png diff --git a/doc/manual/en_US/images/vboxlogo.png b/doc/manual/en_US/images/vboxlogo.png Binary files differnew file mode 100644 index 00000000..1394b447 --- /dev/null +++ b/doc/manual/en_US/images/vboxlogo.png diff --git a/doc/manual/en_US/images/virtual-disk-manager-2.png b/doc/manual/en_US/images/virtual-disk-manager-2.png Binary files differnew file mode 100644 index 00000000..030043ba --- /dev/null +++ b/doc/manual/en_US/images/virtual-disk-manager-2.png diff --git a/doc/manual/en_US/images/virtual-disk-manager.png b/doc/manual/en_US/images/virtual-disk-manager.png Binary files differnew file mode 100644 index 00000000..6e7637d4 --- /dev/null +++ b/doc/manual/en_US/images/virtual-disk-manager.png diff --git a/doc/manual/en_US/images/virtual-hard-disk-wizard.png b/doc/manual/en_US/images/virtual-hard-disk-wizard.png Binary files differnew file mode 100644 index 00000000..4a392779 --- /dev/null +++ b/doc/manual/en_US/images/virtual-hard-disk-wizard.png diff --git a/doc/manual/en_US/images/virtualbox-main-empty.png b/doc/manual/en_US/images/virtualbox-main-empty.png Binary files differnew file mode 100644 index 00000000..a29aa67e --- /dev/null +++ b/doc/manual/en_US/images/virtualbox-main-empty.png diff --git a/doc/manual/en_US/images/virtualbox-main.png b/doc/manual/en_US/images/virtualbox-main.png Binary files differnew file mode 100644 index 00000000..963b709e --- /dev/null +++ b/doc/manual/en_US/images/virtualbox-main.png diff --git a/doc/manual/en_US/images/vm-activity-overview.png b/doc/manual/en_US/images/vm-activity-overview.png Binary files differnew file mode 100644 index 00000000..93e4d3a4 --- /dev/null +++ b/doc/manual/en_US/images/vm-activity-overview.png diff --git a/doc/manual/en_US/images/vm-close.png b/doc/manual/en_US/images/vm-close.png Binary files differnew file mode 100644 index 00000000..0a018c2b --- /dev/null +++ b/doc/manual/en_US/images/vm-close.png diff --git a/doc/manual/en_US/images/vm-groups.png b/doc/manual/en_US/images/vm-groups.png Binary files differnew file mode 100644 index 00000000..0d746db3 --- /dev/null +++ b/doc/manual/en_US/images/vm-groups.png diff --git a/doc/manual/en_US/images/vm-hostkey.png b/doc/manual/en_US/images/vm-hostkey.png Binary files differnew file mode 100644 index 00000000..f59aedb1 --- /dev/null +++ b/doc/manual/en_US/images/vm-hostkey.png diff --git a/doc/manual/en_US/images/vm-settings-harddisk.png b/doc/manual/en_US/images/vm-settings-harddisk.png Binary files differnew file mode 100644 index 00000000..27ac82cf --- /dev/null +++ b/doc/manual/en_US/images/vm-settings-harddisk.png diff --git a/doc/manual/en_US/images/vm-vista-running.png b/doc/manual/en_US/images/vm-vista-running.png Binary files differnew file mode 100644 index 00000000..79f04b09 --- /dev/null +++ b/doc/manual/en_US/images/vm-vista-running.png diff --git a/doc/manual/en_US/man_VBoxHeadless.xml b/doc/manual/en_US/man_VBoxHeadless.xml new file mode 100644 index 00000000..354c0d20 --- /dev/null +++ b/doc/manual/en_US/man_VBoxHeadless.xml @@ -0,0 +1,239 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxHeadless +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="man_vboxheadless" lang="en"> + <refentryinfo> + <pubdate>August 2019</pubdate> + <title>VBoxHeadless</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxHeadless</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxHeadless</refname> + <refpurpose>&product-name; remote desktop server</refpurpose> + <refclass>Oracle VM VirtualBox</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-vboxheadless"> + <command>VBoxHeadless</command> + <arg>--startvm=<group> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group></arg> + <arg>--vrde=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + <arg choice="plain">config</arg> + </group></arg> + <arg>--vrdeproperty=<replaceable>prop-name</replaceable>=[<replaceable>prop-value</replaceable>]</arg> + <arg>--settingspw=[<replaceable>password</replaceable>]</arg> + <arg>--settingspwfile=<replaceable>password-file</replaceable></arg> + <arg>--start-paused=<replaceable>vmname</replaceable></arg> + <arg>--capture</arg> + <arg>--width=<replaceable>width</replaceable></arg> + <arg>--height=<replaceable>height</replaceable></arg> + <arg>--bitrate=<replaceable>bit-rate</replaceable></arg> + <arg>--filename=<replaceable>filename</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxHeadless</command> command is an alternate front + end that enables you to remotely manage virtual machines (VMs). + The front end is a CLI rather than the VirtualBox Manager + graphical user interface (GUI). + </para> + <para> + For information about using this command, see + <xref linkend="vboxheadless" />. + </para> + <refsect2 id="vboxmanage-vboxheadless-command-options"> + <title>Command Options</title> + <variablelist> + <varlistentry> + <term><option>--startvm=<replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></option></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or name + of the VM to start. + </para><para> + Use the <command>VBoxManage list vms</command> command to + obtain VM information. + </para><para> + The short versions of this option are <option>-s</option> + and <option>-startvm</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde=on | off | config</option></term> + <listitem><para> + Specifies how to use the VRDP server. The default value is + <literal>config</literal>. Valid values are as follows: + </para><itemizedlist> + <listitem><para> + <literal>on</literal> enables the VRDP server. + </para><screen>VBoxHeadless --startvm=<replaceable>vmname</replaceable> --vrde=on</screen></listitem> + <listitem><para> + <literal>off</literal> disables the VRDP server. + </para><screen>VBoxHeadless --startvm=<replaceable>vmname</replaceable> --vrde=off</screen></listitem> + <listitem><para> + <literal>config</literal> enables the VRDP server + depending on the VM configuration. + </para><screen>VBoxHeadless --startvm=<replaceable>vmname</replaceable> --vrde=config</screen></listitem> + </itemizedlist><para> + The short version of this option is <option>-v</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrdeproperty=<replaceable>prop-name</replaceable>=<replaceable>prop-value</replaceable></option></term> + <listitem><para> + Specifies a value for one of the following properties: + </para><itemizedlist> + <listitem><para> + The <literal>TCP/Ports</literal> property value is a + comma-separated list of ports to which the VRDE server + can bind. Use a hyphen (<literal>-</literal>) between + two port numbers to specify a range of ports. + </para></listitem> + <listitem><para> + The <literal>TCP/Address</literal> property value is + the interface IP address to which to bind the VRDE + server. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--settingspw=[<replaceable>password</replaceable>]</option></term> + <listitem><para> + Specifies a settings password to access encrypted + settings. If you do not specify the password on the + command line, <command>VBoxHeadless</command> prompts you + for the password. + </para><remark> + This design does not conform to Oracle's security + guidelines. You should not be able to specify a password + on the command line because the password can be seen in a + process listing. + </remark></listitem> + </varlistentry> + <varlistentry> + <term><option>--settingspwfile=<replaceable>password-file</replaceable></option></term> + <listitem><para> + Specifies the file that contains the settings password. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--start-paused=<replaceable>vmname</replaceable></option></term> + <listitem><para> + Starts the specified VM in the paused state. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--capture</option></term> + <listitem><para> + Records the VM screen output to a file. In addition to + this option, you must use the <option>--filename</option> + option to specify the name of the file. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--width=<replaceable>width</replaceable></option></term> + <listitem><para> + Specifies the frame width of the recording in pixels. This + option is associated with the <option>--capture</option> + option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--height=<replaceable>height</replaceable></option></term> + <listitem><para> + Specifies the frame height of the recording in pixels. + This option is associated with the + <option>--capture</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bitrate=<replaceable>bit-rate</replaceable></option></term> + <listitem><para> + Specifies the bit rate of the recording in kilobits per + second. This option is associated with the + <option>--capture</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--filename=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies the name of the file in which to store the + recording. The codec used is based on the file extension + that you choose. You must specify this option if you use + the <option>--capture</option> option. + </para><remark> + Where can we get information about the file extensions + that are supported? + </remark></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following command starts the <literal>ol7u4</literal> VM: + </para> +<screen>$ VBoxHeadless --startvm "ol7u4"</screen> + <para> + The following command starts the <literal>ol7u6</literal> VM in + the Paused state. + </para> +<screen>$ VBoxHeadless --startvm "ol7u6" --start-paused</screen> + <para> + The following command starts the <literal>ol7u6</literal> VM and + records the session. The recording is saved to the + <filename>ol7u6-recording</filename> WebM file. + </para> +<screen>$ VBoxHeadless --startvm "ol7u6" --capture --filename ol7u6-recording.webm</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-list" />, + <xref linkend="vboxmanage-startvm" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-adoptstate.xml b/doc/manual/en_US/man_VBoxManage-adoptstate.xml new file mode 100644 index 00000000..cc35d3d9 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-adoptstate.xml @@ -0,0 +1,112 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage adoptstate +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-adoptstate" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage adoptstate</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-adoptstate</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-adoptstate</refname> + <refpurpose>change a virtual machine's state based on a saved state file</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-adoptstate"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage adoptstate</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="req"><replaceable>state-filename</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage adoptstate</command> command enables you + to change the state of a virtual machine (VM) to a state described + in a saved state file (<filename>.sav</filename>). This action is + referred to as a VM <emphasis>adopting</emphasis> a saved state + file. The saved state file must be separate from the VM + configuration. + </para> + <para> + When you start the VM after adopting the saved state, the VM + restores its state from the saved state file. + </para> + <para> + Only use this command for custom deployments. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or name + of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>state-filename</replaceable></term> + <listitem><para> + Specifies the name of the saved state file. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command adopts a saved state file called + <filename>mystate.sav</filename> by a VM called <literal>vm2</literal>. + A subsequent start of the VM called <literal>vm2</literal> restores the + state from the saved state file <filename>mystate.sav</filename>. + </para> +<screen>$ VBoxManage adoptstate vm2 /home/user/mystate.sav</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-discardstate"/> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-bandwidthctl.xml b/doc/manual/en_US/man_VBoxManage-bandwidthctl.xml new file mode 100644 index 00000000..8a5b9b98 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-bandwidthctl.xml @@ -0,0 +1,307 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage bandwidthctl +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-bandwidthctl" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage bandwidthctl</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-bandwidthctl</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-bandwidthctl</refname> + <refpurpose>manage bandwidth groups</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-bandwidthctl-add"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage bandwidthctl</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">add</arg> + <arg choice="req"><replaceable>bandwidth-group-name</replaceable></arg> + <arg choice="req">--limit=<replaceable>bandwidth-limit</replaceable>[k|m|g|K|M|G]</arg> + <arg choice="req">--type=disk|network</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-bandwidthctl-list"> + <command>VBoxManage bandwidthctl</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">list</arg> + <arg>--machinereadable</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-bandwidthctl-remove"> + <command>VBoxManage bandwidthctl</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">remove</arg> + <arg choice="req"><replaceable>bandwidth-group-name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-bandwidthctl-set"> + <command>VBoxManage bandwidthctl</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">set</arg> + <arg choice="req"><replaceable>bandwidth-group-name</replaceable></arg> + <arg choice="req">--limit=<replaceable>bandwidth-limit</replaceable>[k|m|g|K|M|G]</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage bandwidthctl</command> command enables you + to manage bandwidth groups for virtual machines (VMs). A bandwidth + group specifies the bandwidth limit for the disks or for the + network adapters of a VM. + </para> + <para> + Note that a network bandwidth limit applies only to the outbound + traffic from the VM. The inbound traffic is unlimited. + </para> + <refsect2 id="vboxmanage-bandwidthctl-add"> + <title>Create a Bandwidth Group</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage bandwidthctl add</command> command + creates a bandwidth group for the specified VM. You must specify + whether the bandwidth group is for disks or for networks, and + specify the bandwidth limit. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or the + name of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option><replaceable>bandwidth-group-name</replaceable></option></term> + <listitem><para> + Specifies the name of the bandwidth group. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--type=disk|network</option></term> + <listitem><para> + Specifies the type of the bandwidth group: + <literal>disk</literal> and <literal>network</literal>. + For more information, see + <xref linkend="storage-bandwidth-limit" /> or + <xref linkend="network_bandwidth_limit" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--limit=<replaceable>bandwidth-limit</replaceable>[k|m|g|K|M|G]</option></term> + <listitem><para> + Specifies the bandwidth limit for a bandwidth group. The + default unit is megabytes per second. You can modify this + value while the VM is running. + </para><para> + You can change the unit by appending one of the following + unit specifiers to the bandwidth limit: + </para><itemizedlist> + <listitem><para> + <literal>k</literal> – kilobits per second + </para></listitem> + <listitem><para> + <literal>m</literal> – megabits per second + </para></listitem> + <listitem><para> + <literal>g</literal> – gigabits per second + </para></listitem> + <listitem><para> + <literal>K</literal> – kilobytes per second + </para></listitem> + <listitem><para> + <literal>M</literal> – megabytes per second + </para></listitem> + <listitem><para> + <literal>G</literal> – gigabytes per second + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-bandwidthctl-list"> + <title>List Bandwidth Groups</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage bandwidthctl list</command> command + lists the all the bandwidth groups that have been defined for + the specified VM. Use the <option>--machinereadable</option> + option to produce the output in a machine-readable format, which + uses name-value pairs. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the UUID or the name of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--machinereadable</option></term> + <listitem><para> + Outputs the information about the bandwidth groups in + name-value pairs. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-bandwidthctl-remove"> + <title>Remove a Bandwidth Group</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage bandwidthctl remove</command> command + removes a bandwidth group. + </para> + <note> + <para> + To successfully remove a bandwidth group, ensure that it is + not referenced by any disk or adapter in the running VM. + </para> + </note> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the UUID or the name of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option><replaceable>bandwidth-group-name</replaceable></option></term> + <listitem><para> + Specifies the name of the bandwidth group. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-bandwidthctl-set"> + <title>Modify the Bandwidth Limit of a Bandwidth Group</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage bandwidthctl set</command> command + modifies the bandwidth limit for a bandwidth group. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the UUID or the name of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option><replaceable>bandwidth-group-name</replaceable></option></term> + <listitem><para> + Specifies the name of the bandwidth group. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--limit=<replaceable>bandwidth-limit</replaceable>[k|m|g|K|M|G]</option></term> + <listitem><para> + Specifies the bandwidth limit for a bandwidth group. The + default unit is megabytes per second. You can modify this + value while the VM is running. + </para><para> + You can change the unit by appending one of the following + unit specifiers to the bandwidth limit: + </para><itemizedlist> + <listitem><para> + <literal>k</literal> – kilobits per second + </para></listitem> + <listitem><para> + <literal>m</literal> – megabits per second + </para></listitem> + <listitem><para> + <literal>g</literal> – gigabits per second + </para></listitem> + <listitem><para> + <literal>K</literal> – kilobytes per second + </para></listitem> + <listitem><para> + <literal>M</literal> – megabytes per second + </para></listitem> + <listitem><para> + <literal>G</literal> – gigabytes per second + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following example shows how to use the <command>VBoxManage + bandwidthctl</command> command to create the + <literal>Limit</literal> bandwidth group and set the limit to 20 + Mbps. Then use the <command>VBoxManage modifyvm</command> command + to assign this bandwidth group to the first and second adapters of + the <literal>vm1</literal> VM. + </para> +<screen>$ VBoxManage bandwidthctl "vm1" add Limit --type network --limit 20m +$ VBoxManage modifyvm "vm1" --nicbandwidthgroup1 Limit +$ VBoxManage modifyvm "vm1" --nicbandwidthgroup2 Limit</screen> + <para> + You can dynamically modify the limit of a bandwidth group while + the VM is running. The following example shows how to modify the + limit for the <literal>Limit</literal> bandwidth group from 20 + Mbps to 100 kbps: + </para> +<screen>$ VBoxManage bandwidthctl "vm1" set Limit --limit 100k</screen> + <para> + The following command disables shaping for all adapters in the + <literal>Limit</literal> bandwidth group by specifying a limit of + zero (<literal>0</literal>): + </para> +<screen>$ VBoxManage bandwidthctl "vm1" set Limit --limit 0</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-checkmediumpwd.xml b/doc/manual/en_US/man_VBoxManage-checkmediumpwd.xml new file mode 100644 index 00000000..0157ef73 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-checkmediumpwd.xml @@ -0,0 +1,113 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage checkmediumpwd +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-checkmediumpwd" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage checkmediumpwd</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-checkmediumpwd</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-checkmediumpwd</refname> + <refpurpose>check encryption password on a DEK-encrypted medium or a disk image</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-checkmediumpwd"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage checkmediumpwd</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>filename</replaceable></arg> + </group> + <arg choice="req"><replaceable>password-file</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage checkmediumpwd</command> command checks + the current encryption password on a DEK-encrypted medium or a + disk image. See <xref linkend="diskencryption-encryption" />. + </para> + <para> + The command response indicates if the specified password is + correct. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>filename</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or the + absolute path name of the medium or image. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>password-file</replaceable></term> + <listitem><para> + Specifies the password to check. The password + can be the absolute path name of a password file + on the host OS or the dash character (<literal>-</literal>) + to prompt you for the password on the command line. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following example checks the encryption password for the + <filename>ol7u4-1.vdi</filename> disk image. The password + is contained in a file called <filename>pwfile</filename>. + </para> + <para> + The command returns a message indicating that the specified + password is correct. + </para> +<screen>$ VBoxManage checkmediumpwd "$HOME/VirtualBox VMs/ol7u4/ol7u4-1.vdi" /home/user/pwfile + The given password is correct</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-encryptmedium" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-clonemedium.xml b/doc/manual/en_US/man_VBoxManage-clonemedium.xml new file mode 100644 index 00000000..dec3efc8 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-clonemedium.xml @@ -0,0 +1,214 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage clonemedium +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-clonemedium" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage clonemedium</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-clonemedium</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-clonemedium</refname> + <refpurpose>create a clone of a medium</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-clonemedium"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage clonemedium</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>source-medium</replaceable></arg> + </group> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>target-medium</replaceable></arg> + </group> + <group> + <arg choice="plain">disk</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">floppy</arg> + </group> + <arg>--existing</arg> + <arg>--format=<group choice="plain"> + <arg choice="plain">VDI</arg> + <arg choice="plain">VMDK</arg> + <arg choice="plain">VHD</arg> + <arg choice="plain">RAW</arg> + <arg choice="plain"><replaceable>other</replaceable></arg> + </group></arg> + <arg>--variant=Standard,Fixed,Split2G,Stream,ESX</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage clonemedium</command> command enables you + to clone an existing medium (virtual disk, DVD, or floppy), which + is typically an image file. Only the Universally Unique Identifier + (UUID) differs between the original image and the cloned image. + </para> + <para> + You can use the Virtual Media Manager to transfer the cloned image + to another host system or reimport it into &product-name;. See + <xref linkend="virtual-media-manager" /> and <xref linkend="cloningvdis" />. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>source-medium</replaceable></term> + <listitem><para> + Specifies the UUID or the absolute or relative file name of + the source medium to clone. You can specify the UUID of the + medium only if it is registered. Use the <command>VBoxManage + list hdds</command> command to list registered images. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>target-medium</replaceable></term> + <listitem><para> + Specifies the UUID or the absolute or relative file name of + the target (clone) medium. You can specify the UUID of the + target medium only if it is registered. Use the + <command>VBoxManage list hdds</command> command to list + registered images. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>disk</literal> | <literal>dvd</literal> | <literal>floppy</literal></term> + <listitem><para> + Specifies the type of the medium to clone. Valid values are + <literal>disk</literal>, <literal>dvd</literal>, and + <literal>floppy</literal>. The default value is + <literal>disk</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--existing</option></term> + <listitem><para> + Performs the clone operation by overwriting an existing + target medium. The result is that only the portion of the + source medium that fits into the existing target medium is + copied. + </para><para> + If the target medium is smaller than the source, only the + portion of the source medium up to the size of the target + medium is copied. + </para><para> + If the target medium is larger than the source, the + remaining part of the target medium is unchanged. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--format</option></term> + <listitem><para> + Specifies the file format of the target medium if it differs + from the format of the source medium. Valid values are + <literal>VDI</literal>, <literal>VMDK</literal>, + <literal>VHD</literal>, <literal>RAW</literal>, and + <replaceable>other</replaceable>. + </para><remark> + What file formats can <replaceable>other</replaceable> be? + </remark></listitem> + </varlistentry> + <varlistentry> + <term><option>--variant=Standard,Fixed,Split2G,Stream,ESX</option></term> + <listitem><para> + Specifies the file format variant for the target medium, + which is a comma-separated list of variants. Following are + the valid values: + </para><itemizedlist> + <listitem><para> + <literal>Standard</literal> is the default disk image + type, which has a dynamically allocated file size. + </para></listitem> + <listitem><para> + <literal>Fixed</literal> uses a disk image that has a + fixed file size. + </para></listitem> + <listitem><para> + <literal>Split2G</literal> indicates that the disk image + is split into 2GB segments. This value is for VMDK only. + </para></listitem> + <listitem><para> + <literal>Stream</literal> optimizes the disk image for + downloading. This value is for VMDK only. + </para></listitem> + <listitem><para> + <literal>ESX</literal> is used for some VMWare products. + This value is for VMDK only. + </para></listitem> + </itemizedlist><para> + Note that not all variant combinations are valid. Specifying + incompatible variant values in the list will produce an + error message. + </para></listitem> + </varlistentry> + </variablelist> + <note> + <para> + For compatibility with earlier versions of &product-name;, you + can use the <command>clonevdi</command> and + <command>clonehd</command> commands instead of the + <command>clonemedium</command> command. + </para> + </note> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command creates a clone of the + <filename>disk01.vdi</filename> disk image file. The clone is + called <filename>disk02.vdi</filename>. + </para> +<screen>$ VBoxManage clonemedium disk01.vdi disk02.vdi</screen> + <para> + The following command creates a clone of the + <filename>disk01.vdi</filename> disk image file. The clone is in + VMDK format and is called <filename>disk02.vmdk</filename>. + </para> +<screen>$ VBoxManage clonemedium disk01.vdi disk02.vmdk --format VMDK</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-list" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-clonevm.xml b/doc/manual/en_US/man_VBoxManage-clonevm.xml new file mode 100644 index 00000000..a6e9b58e --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-clonevm.xml @@ -0,0 +1,274 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage clonevm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-clonevm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage clonevm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-clonevm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-clonevm</refname> + <refpurpose>create a clone of an existing virtual machine</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-clonevm"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage clonevm</command> + <arg choice="req"><replaceable>vmname|uuid</replaceable></arg> + + <arg>--basefolder=<replaceable>basefolder</replaceable></arg> + + <arg rep="repeat">--groups=<replaceable>group</replaceable>,</arg> + + <group choice='opt'> + <arg choice='plain'>--mode=machine</arg> + <arg choice='plain'>--mode=machinechildren</arg> + <arg choice='plain'>--mode=all</arg> + </group> + + <arg>--name=<replaceable>name</replaceable></arg> + + <arg rep="repeat">--options=<replaceable>option</replaceable>,</arg> + + <arg>--register</arg> + + <arg>--snapshot=<replaceable>snapshot-name</replaceable></arg> + + <arg>--uuid=<replaceable>uuid</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage clonevm</command> command creates a clone + of an existing virtual machine (VM). The clone can be a full copy + of the VM or a linked copy of a VM. + </para> + <para> + You must specify the name or the universal unique identifier + (UUID) of the VM you want to clone. + </para> + </refsect1> + + <refsect1> + <title>Command Operand and Options</title> + <para> + The following list describes the operand and the options that you + can use with the <command>VBoxManage clonevm</command> command: + </para> + <variablelist> + <varlistentry> + <term><replaceable>vmname|uuid</replaceable></term> + <listitem><para> + Specifies the name or UUID of the VM to clone. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--basefolder=<replaceable>basefolder</replaceable></option></term> + <listitem><para> + Specifies the name of the folder in which to save the + configuration for the new VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--groups=<replaceable>group</replaceable>,...</option></term> + <listitem><para> + Assigns the clone to the specified group or groups. If you + specify more than one group, separate each group name with a + comma. + </para><para> + Note that each group is identified by a group ID that starts + with a slash character (<computeroutput>/</computeroutput>) + so that groups can be nested. By default, a clone is always + assigned membership to the + <computeroutput>/</computeroutput> group. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mode=machine|machineandchildren|all</option></term> + <listitem><para> + Specifies which of the following cloning modes to use: + </para><itemizedlist> + <listitem><para> + <computeroutput>machine</computeroutput> mode clones the + current state of the existing VM without any snapshots. + This is the default mode. + </para></listitem> + <listitem><para> + <computeroutput>machineandchildren</computeroutput> mode + clones the snapshot specified by by the + <option>--snapshot</option> option and all child + snapshots. + </para></listitem> + <listitem><para> + <computeroutput>all</computeroutput> mode clones all + snapshots and the current state of the existing VM. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--name=<replaceable>name</replaceable></option></term> + <listitem><para> + Specifies a new name for the new VM. The default value is + <computeroutput><replaceable>original-name</replaceable> + Clone</computeroutput> where + <replaceable>original-name</replaceable> is the original + name of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--options=<replaceable>option</replaceable>,...</option></term> + <listitem><para> + Specifies how to create the new clone.</para> + <para>The <option>--options</option> argument can be used multiple + times to enable multiple options, or the options can be given as a + comma separated list. The options are case insensitive.</para> + <para>The following options (case-insensitive) are recognized:</para> + <variablelist> + <varlistentry> + <term><option>Link</option></term> + <listitem><para> + Creates a linked clone from a snapshot only. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>KeepAllMACs</option></term> + <listitem><para> + Specifies that the new clone reuses the MAC addresses + of each virtual network card from the existing VM. + </para><para> + If you do not specify this option or the + <option>--options=keepnatmacs</option> option, the + default behavior is to reinitialize the MAC addresses + of each virtual network card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>KeepNATMACs</option></term> + <listitem><para> + Specifies that the new clone reuses the MAC addresses + of each virtual network card from the existing VM when + the network type is NAT. + </para><para> + If you do not specify this option or the + <option>KeepAllMACs</option> option, the + default behavior is to reinitialize the MAC addresses + of each virtual network card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>KeepDiskNames</option></term> + <listitem><para> + Specifies that the new clone reuses the disk image + names from the existing VM. By default, disk images + are renamed. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>KeepHwUUIDs</option></term> + <listitem><para> + Specifies that the new clone reuses the hardware IDs + from the existing VM. By default, new UUIDs are used. + </para></listitem> + </varlistentry> + </variablelist></listitem> + </varlistentry> + <varlistentry> + <term><option>--register</option></term> + <listitem><para> + Automatically registers the new clone in this &product-name; + installation. You can manually register the new VM later by + using the <command>VBoxManage registervm</command> command. + See <xref linkend="vboxmanage-registervm" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--snapshot=<replaceable>snapshot-name</replaceable></option></term> + <listitem><para> + Specifies the snapshot on which to base the new VM. By + default, the clone is created from the current state of the + specified VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Specifies the UUID for the new VM. Ensure that this ID is + unique for the &product-name; instance if you decide to + register this new VM. By default, &product-name; provides a + new UUID. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <para> + The following command creates and registers an exact clone of the + <computeroutput>ol7</computeroutput> VM. The clone is called + <computeroutput>ol7-dev-001</computeroutput>. + </para> + <para> + The new clone includes all of the source VM's snapshots. The new + VM also reuses all network interface MAC addresses, disk names, + and UUIDs from the source VM. + </para> +<screen> +$ VBoxManage clonevm ol7 --name="ol7-dev-001" --register --mode=all \ + --options=keepallmacs --options=keepdisknames --options=keephwuuids +</screen> + <para> + The following command creates and registers a clone of the + <computeroutput>Snapshot 1</computeroutput> snapshot of the + <computeroutput>ol7</computeroutput> VM. The clone is called + <computeroutput>ol7-dev-002</computeroutput>. + </para> +<screen> +$ VBoxManage clonevm ol7 --name="ol7-dev-002" --register --snapshot="Snapshot 1" +</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-registervm" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-closemedium.xml b/doc/manual/en_US/man_VBoxManage-closemedium.xml new file mode 100644 index 00000000..45dcb2f5 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-closemedium.xml @@ -0,0 +1,119 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage closemedium +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-closemedium" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage closemedium</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-closemedium</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-closemedium</refname> + <refpurpose>remove a hard disk, DVD, or floppy image from the media registry</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-closemedium"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage closemedium</command> + <group> + <arg choice="plain">disk</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">floppy</arg> + </group> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>filename</replaceable></arg> + </group> + <arg>--delete</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage closemedium</command> command removes a + hard disk, DVD, or floppy image from the list of known media used + by &product-name;. The image is then unavailable for selection in + the Virtual Media Manager. + </para> + <para> + To use this command, the image must not be attached to any VMs. + </para> + <para> + Optionally, you can request that the image be deleted. + </para> + <variablelist> + <varlistentry> + <term>disk|dvd|floppy</term> + <listitem><para> + Specifies the type of medium. Valid values are + <literal>disk</literal> (hard drive), + <literal>dvd</literal>, or <literal>floppy</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>filename</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or + absolute path name of the medium or image. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--delete</option></term> + <listitem><para> + Deletes the image file. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command removes the disk image file called + <filename>disk01.vdi</filename> from the registry. + </para> +<screen>$ VBoxManage closemedium disk01.vdi</screen> + <para> + The following command removes the disk image file called + <filename>disk01.vdi</filename> from the registry and deletes the + image file. + </para> +<screen>$ VBoxManage closemedium disk01.vdi --delete</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-cloud.xml b/doc/manual/en_US/man_VBoxManage-cloud.xml new file mode 100644 index 00000000..897f9118 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-cloud.xml @@ -0,0 +1,708 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage cloud +--> +<!-- + Copyright (C) 2018-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-cloud" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-05-16 18:12:21 +0200 (Tue, 16 May 2023) $</pubdate> + <title>VBoxManage cloud</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-cloud</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="manual">&product-name;</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>VBoxManage-cloud</refname> + <refpurpose>Manage the cloud entities</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <!-- Cloud list --> + <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <cmdsynopsis id="synopsis-vboxmanage-cloudlist-instances"> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">list</arg> + <arg choice="plain">instances</arg> + <arg>--state=<replaceable>string</replaceable></arg> + <arg>--compartment-id=<replaceable>string</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudlist-images"> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">list</arg> + <arg choice="plain">images</arg> + <arg choice="req">--compartment-id=<replaceable>string</replaceable></arg> + <arg>--state=<replaceable>string</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudlist-vnicattachments"> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">list</arg> + <arg choice="plain">vnicattachments</arg> + <arg choice="req">--compartment-id=<replaceable>string</replaceable></arg> + <arg>--filter=<replaceable>string</replaceable></arg> + </cmdsynopsis> + + <!-- Cloud instance commands --> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-create" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">instance</arg> + <arg choice="plain">create</arg> + <arg choice="req">--domain-name=<replaceable>name</replaceable></arg> + <group choice="req"> + <arg choice="req">--image-id=<replaceable>id</replaceable></arg> + <arg choice="req">--boot-volume-id=<replaceable>id</replaceable></arg> + </group> + <arg choice="req">--display-name=<replaceable>name</replaceable></arg> + <arg choice="req">--shape=<replaceable>type</replaceable></arg> + <arg choice="req">--subnet=<replaceable>id</replaceable></arg> + <arg>--boot-disk-size=<replaceable>size in GB</replaceable></arg> + <arg>--publicip=<replaceable>true/false</replaceable></arg> + <arg>--privateip=<replaceable>IP address</replaceable></arg> + <arg rep="repeat">--public-ssh-key=<replaceable>key string</replaceable></arg> + <arg>--launch-mode=<replaceable>NATIVE/EMULATED/PARAVIRTUALIZED</replaceable></arg> + <arg>--cloud-init-script-path=<replaceable>path to a script</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-info" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">instance</arg> + <arg choice="plain">info</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-terminate" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">instance</arg> + <arg choice="plain">terminate</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-start" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">instance</arg> + <arg choice="plain">start</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-pause" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">instance</arg> + <arg choice="plain">pause</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-reset" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">instance</arg> + <arg choice="plain">reset</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + + <!-- Cloud image commands --> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-create" sepchar=" "> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">image</arg> + <arg choice="plain">create</arg> + <arg choice="req">--display-name=<replaceable>name</replaceable></arg> + <arg>--bucket-name=<replaceable>name</replaceable></arg> + <arg>--object-name=<replaceable>name</replaceable></arg> + <arg>--instance-id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-info" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">image</arg> + <arg choice="plain">info</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-delete" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">image</arg> + <arg choice="plain">delete</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-import" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">image</arg> + <arg choice="plain">import</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + <arg>--bucket-name=<replaceable>name</replaceable></arg> + <arg>--object-name=<replaceable>name</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-export" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">image</arg> + <arg choice="plain">export</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + <arg choice="req">--display-name=<replaceable>name</replaceable></arg> + <arg>--bucket-name=<replaceable>name</replaceable></arg> + <arg>--object-name=<replaceable>name</replaceable></arg> + </cmdsynopsis> + + <!-- Cloud network commands --> + <cmdsynopsis id="synopsis-vboxmanage-cloud-network-setup"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">network setup</arg> + <arg>--gateway-os-name=<replaceable>string</replaceable></arg> + <arg>--gateway-os-version=<replaceable>string</replaceable></arg> + <arg>--gateway-shape=<replaceable>string</replaceable></arg> + <arg>--tunnel-network-name=<replaceable>string</replaceable></arg> + <arg>--tunnel-network-range=<replaceable>string</replaceable></arg> + <arg>--proxy=<replaceable>string</replaceable></arg> + <arg>--compartment-id=<replaceable>string</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloud-network-create"> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">network create</arg> + <arg choice="req">--name=<replaceable>string</replaceable></arg> + <arg choice="req">--network-id=<replaceable>string</replaceable></arg> + <group> + <arg choice="plain">--enable</arg> + <arg choice="plain">--disable</arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloud-network-update"> + <command>VBoxManage cloud network update</command> + <arg choice="req">--name=<replaceable>string</replaceable></arg> + <arg>--network-id=<replaceable>string</replaceable></arg> + <group> + <arg choice="plain">--enable</arg> + <arg choice="plain">--disable</arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloud-network-delete"> + <command>VBoxManage cloud</command> + <arg choice="plain">network delete</arg> + <arg choice="req">--name=<replaceable>string</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloud-network-info"> + <command>VBoxManage cloud</command> + <arg choice="plain">network info</arg> + <arg choice="req">--name=<replaceable>string</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <!-- Cloud commands common options --> + <refsect2 id="vboxmanage-cloud-common-options"> + <title>Common options</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>The word "cloud" is an umbrella for all commands related to the interconnection with the Cloud. + The next common options must be placed between the "cloud" and the following sub-commands:</para> + <variablelist> + <varlistentry> + <term>--provider=<replaceable>name</replaceable></term> + <listitem><para>Short cloud provider name.</para></listitem> + </varlistentry> + <varlistentry> + <term>--profile=<replaceable>name</replaceable></term> + <listitem><para>Cloud profile name. </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <!-- Cloud list commands --> + <refsect2 id="vboxmanage-cloudlist-instances"> + <title>cloud list instances</title> + <remark role="help-copy-synopsis"/> + <para> + Displays the list of the instances for a specified compartment. + </para> + <variablelist> + <varlistentry> + <term>--state<replaceable>"running/paused/terminated"</replaceable></term> + <listitem> + <para>The state of cloud instance. The possible states are "running/paused/terminated" at moment. + If the state isn't provided the list of instances with all possible states is returned. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment-id</option></term> + <listitem> + <para>A compartment is the logical container used to organize and isolate cloud resources. + The different cloud providers can have the different names for this entity. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudlist-images"> + <title>cloud list images</title> + <remark role="help-copy-synopsis"/> + <para> + Displays the list of the images for a specified compartment. + </para> + <variablelist> + <varlistentry> + <term>--state<replaceable>"available/disabled/deleted"</replaceable></term> + <listitem> + <para>The state of cloud image. The possible states are "available/disabled/deleted" at moment. + If the state isn't provided the list of images with all possible states is returned. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment-id</option></term> + <listitem> + <para>A compartment is the logical container used to organize and isolate cloud resources. + The different cloud providers can have the different names for this entity. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudlist-vnicattachments"> + <title>cloud list vnic attachments</title> + <remark role="help-copy-synopsis"/> + <para> + Displays the list of the vnic attachments for a specified compartment. + </para> + <variablelist> + <varlistentry> + <term>--filter<replaceable>"instanceId/vnicId/domainName=string"</replaceable></term> + <listitem> + <para>Filters are used to narrow down the set of Vnic attachments of interest. + This parameter is repeatible. + The possible filters are "instanceId" or "vnicId" or "availabilityDomain" at moment. + The form is "instanceId/vnicId/domainName=[string value]" and can be repeated. + In instance, "--filter instanceId=ocid1.instance.oc1.iad.anuwcl...js6 + --filter vnicId=ocid1.vnic.oc1.iad.abuwcl...jsm + --filter domainName=ergw:US-ASHBURN-AD-2". + But in most cases, this is redundant and one filter is enough. + If the filter isn't provided the whole list of vnic attachments for a specified compartment is returned. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment-id</option></term> + <listitem> + <para>A compartment is the logical container used to organize and isolate cloud resources. + The different cloud providers can have the different names for this entity. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <!-- Cloud instance commands --> + <refsect2 id="vboxmanage-cloudinstance-create"> + <title>cloud instance create</title> + <remark role="help-copy-synopsis"/> + <para> + Creates new instance in the Cloud. + There are two standard ways to create an instance in the Cloud: + 1. Create an instance from an existing custom image. + 2. Create an instance from an existing bootable volume. This bootable volume shouldn't be attached to any instance. + For the 1st approach next parameters are required: image-id, boot-disk-size. + For the 2nd approach next parameters are required: boot-volume-id. + The rest parameters are common for both cases: + display-name, launch-mode, subnet-id, publicIP, privateIP, shape, domain. + </para> + <variablelist> + <varlistentry> + <term><option>--domain-name</option></term><listitem><para>Cloud domain where new instance is created.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--image-id</option></term><listitem><para>Unique identifier which fully identifies a custom image in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--boot-volume-id</option></term><listitem><para>Unique identifier which fully identifies a boot volume in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--display-name</option></term><listitem><para>Name for new instance in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--shape</option></term><listitem><para> The shape of instance, defines the number of CPUs and RAM memory.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--subnet</option></term><listitem><para> Unique identifier which fully identifies an existing subnet in the Cloud which will be used by the instance.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--boot-disk-size</option></term><listitem><para> The size of bootable image in GB. Default is 50GB.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--publicip</option></term><listitem><para>Whether the instance will have a public IP or not.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--privateip</option></term><listitem><para>Private IP address for the created instance.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--public-ssh-key</option></term> + <listitem> + <para>Public SSH key used to connect to the instance via SSH. + This parameter may be repeated if you plan to use more than one key as: + "--public-ssh-key=firstSSHKey --public-ssh-key=secondSSHKey". + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--launch-mode</option></term><listitem><para>The most known values here may be EMULATED, NATIVE, PARAVIRTUALIZED. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloud-init-script-path</option></term><listitem><para>Absolute path to the user cloud-init script.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-info"> + <title>cloud instance info</title> + <para> + Display information about a cloud instance with a specified id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identify the instance in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-terminate"> + <title>cloud instance termination</title> + <para> + Delete a cloud instance with a specified id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identify the instance in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-start"> + <title>cloud instance start</title> + <para> + Start a cloud instance with a specified id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identify the instance in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-pause"> + <title>cloud instance pause</title> + <para> + Pause a cloud instance with a specified id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identify the instance in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-reset"> + <title>cloud instance reset</title> + <para> + Force reset a cloud instance with a specified id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identify the instance in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <!-- Cloud image commands --> + <refsect2 id="vboxmanage-cloudimage-create"> + <title>cloud image create</title> + <remark role="help-copy-synopsis"/> + <para> + Creates new image in the Cloud. + There are two standard ways to create an image in the Cloud: + 1. Create an image from an object in the Cloud Storage; + 2. Create an image from an existing cloud instance. + For the 1st approach next parameters are required: + bucket-name - cloud bucket name where an object is located; + object-name - name of object in the bucket; + display-name - name for new image in the Cloud. + For the 2d approach next parameters are required: + instance-id - Id of instance in the Cloud; + display-name - name for new image in the Cloud. + </para> + <variablelist> + <varlistentry> + <term><option>--display-name</option></term><listitem><para>Name for new image in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bucket-name</option></term><listitem><para>Cloud bucket name where an object is located.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--object-name</option></term><listitem><para>Name of object in the bucket.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--instance-id</option></term><listitem><para>Unique identifier which fully identifies the instance in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-info"> + <title>cloud image info</title> + <remark role="help-copy-synopsis"/> + <para> + Display information about a cloud image with a specified id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identifies the image in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-delete"> + <title>cloud image delete</title> + <remark role="help-copy-synopsis"/> + <para> + Delete an image with a specified id from the Cloud. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identifies the image in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-import"> + <title>cloud image import</title> + <remark role="help-copy-synopsis"/> + <para> + Import an image with a specified id from the Cloud to a local host. + The result is an object in the local "temp" folder on the local host. + Possible approach may have two general steps: + 1. Create an object from an image in the Cloud Storage; + 2. Download the object to the local host. + So the next parameters may be required: + bucket-name - cloud bucket name where the object will be created; + object-name - name of object in the bucket. if parameter "object-name" is absent a displayed image name is used. + If the first step isn't needed only the parameter "id" is required. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identifies the image in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bucket-name</option></term><listitem><para>Cloud bucket name where an object will be created.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--object-name</option></term> + <listitem> + <para> + Name of created object in the bucket. The downloaded object will have this name. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-export"> + <title>cloud image export</title> + <remark role="help-copy-synopsis"/> + <para> + Export an existing VBox image with a specified uuid from a local host to the Cloud. + The result is new image in the Cloud. + Possible approach may have two general steps: + 1. Upload VBox image to the Cloud Storage; + 2. Create an image from the uploaded object. + So the next parameters may be required: + bucket-name -cloud bucket name where the object will be uploaded; + object-name - name of object in the bucket. If parameter "object-name" is absent the image id is used; + display-name - name for new image in the Cloud. + If the first step isn't needed the parameters "id" and "display-name" are required only. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier of the image in the VirtualBox.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--display-name</option></term><listitem><para>Name for new image in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bucket-name</option></term><listitem><para>Cloud bucket name where the image (object) will be uploaded.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--object-name</option></term><listitem><para>Name of object in the bucket.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + + <!-- Cloud network commands --> + <refsect2 id="vboxmanage-cloud-network-setup"> + <title>cloud network setup</title> + <remark role="help-copy-synopsis"/> + <para> + Set up a cloud network environment for the specified cloud profile. + </para> + <variablelist> + <varlistentry> + <term><option>--gateway-os-name</option></term><listitem><para>The name of OS to use for a cloud gateway.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--gateway-os-version</option></term><listitem><para>The version of OS to use for a cloud gateway.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--gateway-shape</option></term><listitem><para>The instance shape to use for a cloud gateway. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tunnel-network-name</option></term><listitem><para>The name of VCN/subnet to use for tunneling.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tunnel-network-range</option></term><listitem><para>The IP address range to use for tunneling. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--proxy</option></term><listitem><para>The proxy URL to be used in local gateway installation.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment-id</option></term><listitem><para>The compartment to create the tunnel network in.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloud-network-create"> + <title>cloud network create</title> + <remark role="help-copy-synopsis"/> + <para> + Create a new cloud network descriptor associated with an existing cloud subnet. + </para> + <variablelist> + <varlistentry> + <term><option>--name</option></term><listitem><para>The name to assign to the cloud network descriptor.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--network-id</option></term><listitem><para>The unique identifier of an existing subnet in the cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--enable</option>, --disable</term> + <listitem><para>Whether to enable the network descriptor or disable it. If not specified, + the network will be enabled.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloud-network-update"> + <title>cloud network update</title> + <remark role="help-copy-synopsis"/> + <para> + Modify an existing cloud network descriptor. + </para> + <variablelist> + <varlistentry> + <term><option>--name</option></term><listitem><para>The name of an existing cloud network descriptor.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--network-id</option></term><listitem><para>The unique identifier of an existing subnet in the cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--enable</option>, --disable</term> + <listitem><para>Whether to enable the network descriptor or disable it.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloud-network-delete"> + <title>cloud network delete</title> + <remark role="help-copy-synopsis"/> + <para> + Delete an existing cloud network descriptor. + </para> + <variablelist> + <varlistentry> + <term><option>--name</option></term><listitem><para>The name of an existing cloud network descriptor.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloud-network-info"> + <title>cloud network info</title> + <remark role="help-copy-synopsis"/> + <para> + Display information about a cloud network descriptor. + </para> + <variablelist> + <varlistentry> + <term><option>--name</option></term><listitem><para>The name of an existing cloud network descriptor.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsect1> + +</refentry> + diff --git a/doc/manual/en_US/man_VBoxManage-cloudimage.xml b/doc/manual/en_US/man_VBoxManage-cloudimage.xml new file mode 100644 index 00000000..fabe73c3 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-cloudimage.xml @@ -0,0 +1,242 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage cloud image +--> +<!-- + Copyright (C) 2018-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-cloudimage" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage cloud image</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-cloudimage</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-cloudimage</refname> + <refpurpose>Manage the cloud images</refpurpose> + <refclass>Oracle VM VirtualBox</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-create" sepchar=" "> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">image</arg> + <arg choice="plain">create</arg> + <arg choice="req">--display-name=<replaceable>name</replaceable></arg> + <arg>--bucket-name=<replaceable>name</replaceable></arg> + <arg>--object-name=<replaceable>name</replaceable></arg> + <arg>--instance-id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-info" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">image</arg> + <arg choice="plain">info</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-delete" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">image</arg> + <arg choice="plain">delete</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-import" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">image</arg> + <arg choice="plain">import</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + <arg>--bucket-name=<replaceable>name</replaceable></arg> + <arg>--object-name=<replaceable>name</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-export" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">image</arg> + <arg choice="plain">export</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + <arg choice="req">--display-name=<replaceable>name</replaceable></arg> + <arg>--bucket-name=<replaceable>name</replaceable></arg> + <arg>--object-name=<replaceable>name</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <refsect2 id="vboxmanage-cloudimage-common-options"> + <title>Common options</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>The subcommands of <command>cloudimage</command> implement the standard operations for a cloud image + like create/delete/show/import/export. The next common options must be placed between the "cloud" and the following sub-commands:</para> + <variablelist> + <varlistentry> + <term>--provider=<replaceable>name</replaceable></term> + <listitem><para>Short cloud provider name.</para></listitem> + </varlistentry> + <varlistentry> + <term>--profile=<replaceable>name</replaceable></term> + <listitem><para>Cloud profile name. </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-create"> + <title>cloud image create</title> + <remark role="help-copy-synopsis"/> + <para> + Creates new image in the Cloud. + There are two standard ways to create an image in the Cloud: + 1. Create an image from an object in the Cloud Storage; + 2. Create an image from an existing cloud instance. + For the 1st approach next parameters are required: + bucket-name - cloud bucket name where an object is located; + object-name - name of object in the bucket; + display-name - name for new image in the Cloud. + For the 2d approach next parameters are required: + instance-id - Id of instance in the Cloud; + display-name - name for new image in the Cloud. + </para> + <variablelist> + <varlistentry> + <term><option>--display-name</option></term><listitem><para>Name for new image in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bucket-name</option></term><listitem><para>Cloud bucket name where an object is located.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--object-name</option></term><listitem><para>Name of object in the bucket.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--instance-id</option></term><listitem><para>Unique identifier which fully identifies the instance in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-info"> + <title>cloud image info</title> + <remark role="help-copy-synopsis"/> + <para> + Display information about a cloud image with a specified id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identifies the image in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-delete"> + <title>cloud image delete</title> + <remark role="help-copy-synopsis"/> + <para> + Delete an image with a specified id from the Cloud. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identifies the image in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-import"> + <title>cloud image import</title> + <remark role="help-copy-synopsis"/> + <para> + Import an image with a specified id from the Cloud to a local host. + The result is an object in the local "temp" folder on the local host. + Possible approach may have two general steps: + 1. Create an object from an image in the Cloud Storage; + 2. Download the object to the local host. + So the next parameters may be required: + bucket-name - cloud bucket name where the object will be created; + object-name - name of object in the bucket. if parameter "object-name" is absent a displayed image name is used. + If the first step isn't needed only the parameter "id" is required. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identifies the image in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bucket-name</option></term><listitem><para>Cloud bucket name where an object will be created.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--object-name</option></term> + <listitem> + <para> + Name of created object in the bucket. The downloaded object will have this name. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-export"> + <title>cloud image export</title> + <remark role="help-copy-synopsis"/> + <para> + Export an existing VBox image with a specified uuid from a local host to the Cloud. + The result is new image in the Cloud. + Possible approach may have two general steps: + 1. Upload VBox image to the Cloud Storage; + 2. Create an image from the uploaded object. + So the next parameters may be required: + bucket-name -cloud bucket name where the object will be uploaded; + object-name - name of object in the bucket. If parameter "object-name" is absent the image id is used; + display-name - name for new image in the Cloud. + If the first step isn't needed the parameters "id" and "display-name" are required only. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier of the image in the VirtualBox.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--display-name</option></term><listitem><para>Name for new image in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bucket-name</option></term><listitem><para>Cloud bucket name where the image (object) will be uploaded.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--object-name</option></term><listitem><para>Name of object in the bucket.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + +</refentry> + diff --git a/doc/manual/en_US/man_VBoxManage-cloudinstance.xml b/doc/manual/en_US/man_VBoxManage-cloudinstance.xml new file mode 100644 index 00000000..7f5cad34 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-cloudinstance.xml @@ -0,0 +1,227 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + manpage, user manual, usage: VBoxManage cloud instance +--> +<!-- + Copyright (C) 2018-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-cloudinstance" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage cloud instance</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-cloudinstance</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-cloudinstance</refname> + <refpurpose>Manage the cloud instances</refpurpose> + <refclass>Oracle VM VirtualBox</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-create" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">instance</arg> + <arg choice="plain">create</arg> + <arg choice="req">--domain-name=<replaceable>name</replaceable></arg> + <group choice="req"> + <arg choice="req">--image-id=<replaceable>id</replaceable></arg> + <arg choice="req">--boot-volume-id=<replaceable>id</replaceable></arg> + </group> + <arg choice="req">--display-name=<replaceable>name</replaceable></arg> + <arg choice="req">--shape=<replaceable>type</replaceable></arg> + <arg choice="req">--subnet=<replaceable>id</replaceable></arg> + <arg>--boot-disk-size=<replaceable>size in GB</replaceable></arg> + <arg>--publicip=<replaceable>true/false</replaceable></arg> + <arg>--privateip=<replaceable>IP address</replaceable></arg> + <arg rep="repeat">--public-ssh-key=<replaceable>key string</replaceable></arg> + <arg>--launch-mode=<replaceable>NATIVE/EMULATED/PARAVIRTUALIZED</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-info" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">instance</arg> + <arg choice="plain">info</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-terminate" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">instance</arg> + <arg choice="plain">terminate</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-start" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">instance</arg> + <arg choice="plain">start</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-pause" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">instance</arg> + <arg choice="plain">pause</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <refsect2 id="vboxmanage-cloudinstance-common-options"> + <title>Common options</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>The subcommands of <command>cloudinstance</command> implement the standard operations for a cloud instance + like start/pause/show/terminate. The next common options must be placed between the "cloud" and the following sub-commands:</para> + <variablelist> + <varlistentry> + <term>--provider=<replaceable>name</replaceable></term> + <listitem><para>Short cloud provider name.</para></listitem> + </varlistentry> + <varlistentry> + <term>--profile=<replaceable>name</replaceable></term> + <listitem><para>Cloud profile name. </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-create"> + <title>cloud instance create</title> + <remark role="help-copy-synopsis"/> + <para> + Creates new instance in the Cloud. + There are two standard ways to create an instance in the Cloud: + 1. Create an instance from an existing custom image. + 2. Create an instance from an existing bootable volume. This bootable volume shouldn't be attached to any instance. + For the 1st approach next parameters are required: image-id and boot-disk-size. + For the 2nd approach next parameters are required: boot-volume-id; + The rest parameters are common for both cases: + display-name, launch-mode, subnet-id, publicIP, privateIP, shape, domain. + </para> + <variablelist> + <varlistentry> + <term><option>--domain-name</option></term><listitem><para>Cloud domain where new instance is created.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--image-id</option></term><listitem><para>Unique identifier which fully identifies a custom image in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--boot-volume-id</option></term><listitem><para>Unique identifier which fully identifies a boot volume in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--display-name</option></term><listitem><para>Name for new instance in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--shape</option></term><listitem><para> The shape of instance, defines the number of CPUs and RAM memory.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--subnet</option></term><listitem><para> Unique identifier which fully identifies an existing subnet in the Cloud which will be used by the instance.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--boot-disk-size</option></term><listitem><para> The size of bootable image in GB. Default is 50GB.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--publicip</option></term><listitem><para>Whether the instance will have a public IP or not.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--privateip</option></term><listitem><para>Private IP address for the created instance.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--public-ssh-key</option></term> + <listitem> + <para>Public SSH key used to connect to the instance via SSH. + This parameter may be repeated if you plan to use more than one key as: + "--public-ssh-key=firstSSHKey --public-ssh-key=secondSSHKey". + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--launch-mode</option></term><listitem><para>The most known values here may be EMULATED, NATIVE, PARAVIRTUALIZED. </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-info"> + <title>cloud instance info</title> + <para> + Display information about a cloud instance with a specified id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identify the instance in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-terminate"> + <title>cloud instance termination</title> + <para> + Delete a cloud instance with a specified id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identify the instance in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-start"> + <title>cloud instance start</title> + <para> + Start a cloud instance with a specified id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identify the instance in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-pause"> + <title>cloud instance pause</title> + <para> + Pause a cloud instance with a specified id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identify the instance in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-cloudlist.xml b/doc/manual/en_US/man_VBoxManage-cloudlist.xml new file mode 100644 index 00000000..91eb8b70 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-cloudlist.xml @@ -0,0 +1,142 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage cloud list +--> +<!-- + Copyright (C) 2018-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-cloudlist" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage cloud list</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-cloudlist</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-cloudlist</refname> + <refpurpose>The cloud list command gives information about some standard entities in the every Cloud + and which can be represented by the list like the list of instances/disk images/networks and etc</refpurpose> + <refclass>Oracle VM VirtualBox</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-cloudlist-instances"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">list</arg> + <arg choice="plain">instances</arg> + <arg>--state=<replaceable>string</replaceable></arg> + <arg>--compartment-id=<replaceable>string</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudlist-images"> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">list</arg> + <arg choice="plain">images</arg> + <arg choice="req">--compartment-id=<replaceable>string</replaceable></arg> + <arg>--state=<replaceable>string</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <refsect2 id="vboxmanage-cloud-common-options"> + <title>Common options</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>The word "cloud" is an umbrella for all commands related to the interconnection with the Cloud. + The following common options must be placed between the "cloud" and the following command, in our case "list":</para> + <variablelist> + <varlistentry> + <term>--provider=<replaceable>name</replaceable></term> + <listitem><para>Short cloud provider name.</para></listitem> + </varlistentry> + <varlistentry> + <term>--profile=<replaceable>name</replaceable></term> + <listitem><para>Cloud profile name. </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudlist-instances"> + <title>cloud list instances</title> + <remark role="help-copy-synopsis"/> + <para> + Displays the list of the instances for a specified compartment. + </para> + <variablelist> + <varlistentry> + <term>--state<replaceable>"running/paused/terminated"</replaceable></term> + <listitem> + <para>The state of cloud instance. The possible states are "running/paused/terminated" at moment. + If the state isn't provided the list of instances with all possible states is returned. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment-id</option></term> + <listitem> + <para>A compartment is the logical container used to organize and isolate cloud resources. + The different cloud providers can have the different names for this entity. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudlist-images"> + <title>cloud list images</title> + <remark role="help-copy-synopsis"/> + <para> + Displays the list of the images for a specified compartment. + </para> + <variablelist> + <varlistentry> + <term>--state<replaceable>"available/disabled/deleted"</replaceable></term> + <listitem> + <para>The state of cloud image. The possible states are "available/disabled/deleted" at moment. + If the state isn't provided the list of images with all possible states is returned. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment-id</option></term> + <listitem> + <para>A compartment is the logical container used to organize and isolate cloud resources. + The different cloud providers can have the different names for this entity. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> +</refentry> + diff --git a/doc/manual/en_US/man_VBoxManage-cloudprofile.xml b/doc/manual/en_US/man_VBoxManage-cloudprofile.xml new file mode 100644 index 00000000..ad70eaa6 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-cloudprofile.xml @@ -0,0 +1,190 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage cloudprofile +--> +<!-- + Copyright (C) 2018-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-cloudprofile" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage cloudprofile</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-cloudprofile</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-cloudprofile</refname> + <refpurpose>Manage the cloud profiles</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-cloudprofile-add"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage cloudprofile</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">add</arg> + <arg>--clouduser=<replaceable>unique id</replaceable></arg> + <arg>--fingerprint=<replaceable>MD5 string</replaceable></arg> + <arg>--keyfile=<replaceable>path</replaceable></arg> + <arg>--passphrase=<replaceable>string</replaceable></arg> + <arg>--tenancy=<replaceable>unique id</replaceable></arg> + <arg>--compartment=<replaceable>unique id</replaceable></arg> + <arg>--region=<replaceable>string</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudprofile-update"> + <command>VBoxManage cloudprofile</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">update</arg> + <arg>--clouduser=<replaceable>unique id</replaceable></arg> + <arg>--fingerprint=<replaceable>MD5 string</replaceable></arg> + <arg>--keyfile=<replaceable>path</replaceable></arg> + <arg>--passphrase=<replaceable>string</replaceable></arg> + <arg>--tenancy=<replaceable>unique id</replaceable></arg> + <arg>--compartment=<replaceable>unique id</replaceable></arg> + <arg>--region=<replaceable>string</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudprofile-delete"> + <command>VBoxManage cloudprofile</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">delete</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudprofile-show"> + <command>VBoxManage cloudprofile</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">show</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <refsect2 id="vboxmanage-cloudprofile-common-options"> + <title>Common options</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>The subcommands of <command>cloudprofile</command> implement the standard CRUD operations for a cloud profile. + The next common options must be placed between the "cloud" and the following sub-commands:</para> + <variablelist> + <varlistentry> + <term>--provider=<replaceable>name</replaceable></term> + <listitem><para>Short cloud provider name.</para></listitem> + </varlistentry> + <varlistentry> + <term>--profile=<replaceable>name</replaceable></term> + <listitem><para>Cloud profile name. </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudprofile-add"> + <title>cloudprofile add</title> + <remark role="help-copy-synopsis"/> + <para> + Add new cloud profile for a specified cloud provider. + </para> + <variablelist> + <varlistentry> + <term><option>--clouduser</option></term><listitem><para>The name which fully identifies the user in the specified cloud provider.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--fingerprint</option></term><listitem><para>Fingerprint for the key pair being used.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--keyfile</option></term><listitem><para>Full path and filename of the private key. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--passphrase</option></term><listitem><para>Passphrase used for the key, if it is encrypted.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tenancy</option></term><listitem><para>ID of your tenancy. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment</option></term><listitem><para>ID of your compartment.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--region</option></term><listitem><para>Region name. Region is where you plan to deploy an application.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudprofile-show"> + <title>cloudprofile show</title> + <remark role="help-copy-synopsis"/> + <para> + Display information about a cloud profile for a specified cloud provider. + </para> + </refsect2> + + <refsect2 id="vboxmanage-cloudprofile-update"> + <title>cloudprofile update</title> + <remark role="help-copy-synopsis"/> + <para> + Modify a cloud profile for the specified cloud provider. + </para> + <variablelist> + <varlistentry> + <term><option>--clouduser</option></term><listitem><para>The name which fully identifies the user in the specified cloud provider.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--fingerprint</option></term><listitem><para>Fingerprint for the key pair being used.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--keyfile</option></term><listitem><para>Full path and filename of the private key. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--passphrase</option></term><listitem><para>Passphrase used for the key, if it is encrypted.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tenancy</option></term><listitem><para>ID of your tenancy. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment</option></term><listitem><para>ID of your compartment.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--region</option></term><listitem><para>Region name. Region is where you plan to deploy an application.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudprofile-delete"> + <title>cloudprofile delete</title> + <remark role="help-copy-synopsis"/> + <para> + Delete a cloud profile for a specified cloud provider. + </para> + </refsect2> + + </refsect1> + +</refentry> + diff --git a/doc/manual/en_US/man_VBoxManage-common.xml b/doc/manual/en_US/man_VBoxManage-common.xml new file mode 100644 index 00000000..b661c446 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-common.xml @@ -0,0 +1,282 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-common" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage</refname> + <refpurpose>&product-name; command-line interface</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-common"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage</command> + <group> + <arg choice="plain">-V</arg> + <arg choice="plain">--version</arg> + </group> + <arg>--dump-build-type</arg> + <group> + <arg choice="plain">-q</arg> + <arg choice="plain">--nologo</arg> + </group> + <arg>--settingspw=<replaceable>password</replaceable></arg> + <arg>--settingspwfile=<replaceable>pw-file</replaceable></arg> + <arg>@<replaceable>response-file</replaceable></arg> + <arg><arg>help</arg> <replaceable>subcommand</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage</command> command is the command-line + interface (CLI) for the &product-name; software. The CLI supports + all the features that are available with the &product-name; + graphical user interface (GUI). In addition, you can use the + <command>VBoxManage</command> command to manage the features of + the virtualization engine that cannot be managed by the GUI. + </para> + <para> + Each time you invoke the <command>VBoxManage</command> command, + only one command is executed. Note that some + <command>VBoxManage</command> subcommands invoke several + subcommands. + </para> + <para> + Run the <command>VBoxManage</command> command from the command + line of the host operating system (OS) to control &product-name; + software. + </para> + <para> + The <command>VBoxManage</command> command is stored in the + following locations on the host system: + </para> + <itemizedlist> + <listitem><para> + <emphasis role="bold">Linux:</emphasis> + <filename>/usr/bin/VBoxManage</filename> + </para></listitem> + <listitem><para> + <emphasis role="bold">Mac OS X:</emphasis> + <filename>/Applications/VirtualBox.app/Contents/MacOS/VBoxManage</filename> + </para></listitem> + <listitem><para> + <emphasis role="bold">Oracle Solaris:</emphasis> + <filename>/opt/VirtualBox/bin/VBoxManage</filename> + </para></listitem> + <listitem><para> + <emphasis role="bold">Windows:</emphasis> + <filename>C:\Program + Files\Oracle\VirtualBox\VBoxManage.exe</filename> + </para></listitem> + </itemizedlist> + <para> + In addition to managing virtual machines (VMs) with this CLI or + the GUI, you can use the <command>VBoxHeadless</command> CLI to + manage VMs remotely. + </para> + <para> + The <command>VBoxManage</command> command performs particular + tasks by using subcommands, such as <command>list</command>, + <command>createvm</command>, and <command>startvm</command>. See + the associated information for each <command>VBoxManage</command> + subcommand. + </para> + <para> + If required, specify the VM by its name or by its Universally + Unique Identifier (UUID). + </para> + <para> + Use the <command>VBoxManage list vms</command> command to obtain + information about all currently registered VMs, including the VM + names and associated UUIDs. + </para> + <para> + Note that you must enclose the entire VM name in double quotes if + it contains spaces. + </para> + <refsect2 id="vboxmanage-common-options"> + <title>General Options</title> + <variablelist> + <varlistentry> + <term><option>--nologo</option></term> + <listitem><para> + Suppresses the output of the logo information, which is + useful for scripts. + </para><para> + The short version of this option is <option>-q</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--settingspw=[<replaceable>password</replaceable>]</option></term> + <listitem><para> + Specifies the settings password. You can optionally + specify the password as an argument to this option. If you + do not specify the password in this way, the + <command>VBoxManage</command> command prompts you for the + password. + </para><para> + The settings password is a security feature that encrypts + stored settings, which are stored as plain text by + default. + </para><para> + You cannot unencrypt encrypted settings. So, if the + settings are encrypted, you must continue to specify the + <option>--settingspw</option> or + <option>--settingspwfile</option> option. + </para><para> + Only the iSCSI secret is encrypted at this time. + </para><remark> + This design does not conform to Oracle's security + guidelines. You should not be able to specify a password + on the command line because the password can be seen in a + process listing. + </remark></listitem> + </varlistentry> + <varlistentry> + <term><option>--settingspwfile=<replaceable>pw-filename</replaceable></option></term> + <listitem><para> + Specifies the file that contains the settings password. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--version</option></term> + <listitem><para> + Shows version information about the + <command>VBoxManage</command> command. + </para><para> + The short version of this option is <option>-V</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term>@<replaceable>response-file</replaceable></term> + <listitem><para> + Loads arguments from the specified Bourne shell response + file. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>subcommand</replaceable></term> + <listitem><para> + Specifies one of the <command>VBoxManage</command> + subcommands, such as <command>controlvm</command>, + <command>createvm</command>, <command>list</command>, + <command>modifyvm</command>, + <command>showvminfo</command>, <command>startvm</command>, + <command>storageattach</command>, and + <command>storagectl</command>. + </para><para> + Each subcommand is described in its own command topic, + some of which are shown in See Also sections. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following command creates a virtual machine called + <literal>Win8</literal> and registers it with &product-name; by + using the <option>--register</option> option. + </para> +<screen>$ VBoxManage createvm --name "Win8" --register +Virtual machine 'Win8' is created. +UUID: <replaceable>UUID-string</replaceable> +Settings file: '/home/<replaceable>username</replaceable>/VirtualBox VMs/Win8/Win8.vbox'</screen> + <para> + The command output shows that the <literal>Win8</literal> VM is + assigned a UUID and an XML machine settings file. + </para> + <para> + You can use the <command>VBoxManage showvminfo</command> command + to view the configuration information of a VM. + </para> + <para> + The following example uses the <command>VBoxManage + modifyvm</command> command to change the amount of memory for the + <literal>Windows XP</literal> VM to be 1024 megabytes: + </para> +<screen>$ VBoxManage modifyvm "Windows XP" --memory 1024</screen> + <para> + Note that you can use the <command>VBoxManage modifyvm</command> + command even when the VM is powered off. + </para> + <para> + You can use the <command>VBoxManage storagectl</command> command + or the <command>VBoxManage storageattach</command> command to + modify the storage configuration for a VM. For example, to create + a SATA storage controller called <literal>sata01</literal> and add + it to the <literal>ol7</literal> VM: + </para> +<screen>$ VBoxManage storagectl ol7 --name "sata01" --add sata</screen> + <para> + Use the <command>VBoxManage startvm</command> command to start a + VM that is currently powered off. For example, to start the + <literal>win7</literal> VM: + </para> +<screen>$ VBoxManage startvm win7</screen> + <para> + Use the <command>VBoxManage controlvm</command> command to pause + or save a VM that is currently running. You can also use this + command to modify settings for the VM. For example, to enable + audio input for the <literal>ol6u9</literal> VM. + </para> +<screen>$ VBoxManage controlvm ol6u9 audioin on</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-controlvm" />, + <xref linkend="vboxmanage-createvm" />, + <xref linkend="vboxmanage-list" />, + <xref linkend="vboxmanage-modifyvm" />, + <xref linkend="vboxmanage-showvminfo" />, + <xref linkend="vboxmanage-startvm" />, + <xref linkend="vboxmanage-storageattach" />, + <xref linkend="vboxmanage-storagectl" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-controlvm.xml b/doc/manual/en_US/man_VBoxManage-controlvm.xml new file mode 100644 index 00000000..21b337f8 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-controlvm.xml @@ -0,0 +1,2133 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage controlvm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-controlvm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage controlvm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-controlvm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-controlvm</refname> + <refpurpose>change state and settings for a running virtual machine</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-controlvm-pause"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">pause</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-resume"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">resume</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-reset"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">reset</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-poweroff"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">poweroff</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-savestate"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">savestate</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-acpipowerbutton"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">acpipowerbutton</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-acpisleepbutton"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">acpisleepbutton</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-reboot"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">reboot</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-shutdown"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">shutdown</arg> + <arg choice="opt">--force</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-keyboardputscancode"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">keyboardputscancode</arg> + <arg choice="req"><replaceable>hex</replaceable></arg> + <arg rep="repeat"><replaceable>hex</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-keyboardputstring"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">keyboardputstring</arg> + <arg choice="req"><replaceable>string</replaceable></arg> + <arg rep="repeat"><replaceable>string</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-keyboardputfile"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">keyboardputfile</arg> + <arg choice="req"><replaceable>filename</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-setlinkstate"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">setlinkstate<replaceable>N</replaceable></arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-nic"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">nic<replaceable>N</replaceable></arg> + <group choice="req"> + <arg choice="plain">null</arg> + <arg choice="plain">nat</arg> + <arg choice="plain">bridged</arg> + <arg choice="plain">intnet</arg> + <arg choice="plain">hostonly</arg> + <arg choice="plain">generic</arg> + <arg choice="plain">natnetwork</arg> + </group> + <arg><replaceable>device-name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-nictrace"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">nictrace<replaceable>N</replaceable></arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-nictracefile"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">nictracefile<replaceable>N</replaceable></arg> + <arg choice="req"><replaceable>filename</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-nicproperty"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">nicproperty<replaceable>N</replaceable></arg> + <arg choice="req"><replaceable>prop-name</replaceable>=<replaceable>prop-value</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-nicpromisc"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">nicpromisc<replaceable>N</replaceable></arg> + <group choice="req"> + <arg choice="plain">deny</arg> + <arg choice="plain">allow-vms</arg> + <arg choice="plain">allow-all</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-natpf"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">natpf<replaceable>N</replaceable></arg> + <group choice="req"> + <arg choice="plain">[<replaceable>rulename</replaceable>]<arg choice="plain">,tcp</arg></arg> + <arg choice="plain">udp,<arg><replaceable>host-IP</replaceable></arg>,<arg choice="plain"><replaceable>hostport</replaceable>,</arg><arg><replaceable>guest-IP</replaceable></arg>,<arg choice="plain"><replaceable>guestport</replaceable></arg></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-natpf-delete"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">natpf<replaceable>N</replaceable> delete</arg> + + <arg choice="req"><replaceable>rulename</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-guestmemoryballoon"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">guestmemoryballoon</arg> + <arg choice="req"><replaceable>balloon-size</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-usbattach"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">usbattach</arg> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>address</replaceable></arg> + </group> + <arg>--capturefile=<replaceable>filename</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-usbdetach"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">usbdetach</arg> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>address</replaceable></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-audioin"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">audioin</arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-audioout"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">audioout</arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-clipboard-mode"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">clipboard mode</arg> + <group choice="req"> + <arg choice="plain">disabled</arg> + <arg choice="plain">hosttoguest</arg> + <arg choice="plain">guesttohost</arg> + <arg choice="plain">bidirectional</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-clipboard-filetransfers"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">clipboard filetransfers</arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-draganddrop"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">draganddrop</arg> + <group choice="req"> + <arg choice="plain">disabled</arg> + <arg choice="plain">hosttoguest</arg> + <arg choice="plain">guesttohost</arg> + <arg choice="plain">bidirectional</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-vrde"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">vrde</arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-vrdeport"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">vrdeport</arg> + <arg choice="req"><replaceable>port</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-vrdeproperty"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">vrdeproperty</arg> + <arg choice="req"><replaceable>prop-name</replaceable>=<replaceable>prop-value</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-vrdevideochannelquality"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">vrdevideochannelquality</arg> + <arg choice="req"><replaceable>percentage</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-setvideomodehint"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">setvideomodehint</arg> + <arg choice="req"><replaceable>xres</replaceable></arg> + <arg choice="req"><replaceable>yres</replaceable></arg> + <arg choice="req"><replaceable>bpp</replaceable></arg> + <arg><arg><replaceable>display</replaceable></arg><group> + <arg choice="plain">enabled:yes | no</arg> + <arg><replaceable>x-origin</replaceable> <replaceable>y-origin</replaceable></arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-setscreenlayout"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">setscreenlayout</arg> + <arg choice="req"><replaceable>display</replaceable></arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">primary <replaceable>x-origin</replaceable> <replaceable>y-origin</replaceable> <replaceable>x-resolution</replaceable> <replaceable>y-resolution</replaceable> <replaceable>bpp</replaceable></arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-screenshotpng"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">screenshotpng</arg> + <arg choice="req"><replaceable>filename</replaceable></arg> + <arg><replaceable>display</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">recording</arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-screens"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">recording screens</arg> + <group choice="req"> + <arg choice="plain">all</arg> + <arg choice="plain">none</arg> + <arg choice="plain"><replaceable>screen-ID</replaceable>[,<replaceable>screen-ID</replaceable>...]</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-filename"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">recording filename</arg> + <arg choice="req">filename</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-videores"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">recording videores</arg> + <arg choice="req"><replaceable>width</replaceable>x<replaceable>height</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-videorate"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">recording videorate</arg> + <arg choice="req"><replaceable>rate</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-videofps"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">recording videofps</arg> + <arg choice="req"><replaceable>fps</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-maxtime"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">recording maxtime</arg> + <arg choice="req"><replaceable>sec</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-maxfilesize"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">recording maxfilesize</arg> + <arg choice="req"><replaceable>MB</replaceable></arg> + </cmdsynopsis> + + <!-- + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-opts"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">recording opts</arg> + <arg choice="req"><replaceable>key</replaceable>=<arg><replaceable>value</replaceable></arg></arg> + </cmdsynopsis> + --> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-setcredentials"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">setcredentials</arg> + <arg choice="req"><replaceable>username</replaceable></arg> + <arg choice="plain">--passwordfile=<group choice="req"> + <arg choice="plain"><replaceable>filename</replaceable></arg> + <arg choice="plain"><replaceable>password</replaceable></arg> + </group></arg> + <arg choice="req"><replaceable>domain-name</replaceable></arg> + <arg choice="plain">--allowlocallogon=<group choice="req"> + <arg choice="plain">yes</arg> + <arg choice="plain">no</arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-teleport"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">teleport</arg> + <arg choice="req">--host=<replaceable>host-name</replaceable></arg> + <arg choice="req">--port=<replaceable>port-name</replaceable></arg> + <arg>--maxdowntime=<replaceable>msec</replaceable></arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>filename</replaceable></arg> + <arg choice="plain">--password=<replaceable>password</replaceable></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-plugcpu"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">plugcpu</arg> + <arg choice="req"><replaceable>ID</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-unplugcpu"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">unplugcpu</arg> + <arg choice="req"><replaceable>ID</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-cpuexecutioncap"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">cpuexecutioncap</arg> + <arg choice="req"><replaceable>num</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-vm-process-priority"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">vm-process-priority</arg> + <group choice="req"> + <arg choice="plain">default</arg> + <arg choice="plain">flat</arg> + <arg choice="plain">low</arg> + <arg choice="plain">normal</arg> + <arg choice="plain">high</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-webcam-attach"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">webcam attach</arg> + <arg><replaceable>pathname</replaceable><arg><replaceable>settings</replaceable></arg></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-webcam-detach"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">webcam detach</arg> + <arg><replaceable>pathname</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-webcam-list"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">webcam list</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-addencpassword"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">addencpassword</arg> + <arg choice="req"><replaceable>ID</replaceable></arg> + <group choice="req"> + <arg choice="plain"><replaceable>password-file</replaceable></arg> + <arg choice="plain">-</arg> + </group> + <arg>--removeonsuspend=<group choice="plain"> + <arg choice="plain">yes</arg> + <arg choice="plain">no</arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-removeencpassword"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">removeencpassword</arg> + <arg choice="req"><replaceable>ID</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-removeallencpasswords"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">removeallencpasswords</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-changeuartmode"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">changeuartmode<replaceable>N</replaceable></arg> + <group choice="plain"> + <arg choice="plain">disconnected</arg> + <arg choice="plain">server <replaceable>pipe-name</replaceable></arg> + <arg choice="plain">client <replaceable>pipe-name</replaceable></arg> + <arg choice="plain">tcpserver <replaceable>port</replaceable></arg> + <arg choice="plain">tcpclient <replaceable>hostname</replaceable>:<replaceable>port</replaceable></arg> + <arg choice="plain">file <replaceable>filename</replaceable></arg> + <arg choice="plain"><replaceable>device-name</replaceable></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-autostart-enabled"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">autostart-enabled<replaceable>N</replaceable></arg> + <group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-autostart-delay"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">autostart-delay<replaceable>seconds</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage controlvm</command> command enables you to + change the state of a running virtual machine (VM). The following + sections describe the subcommands that you can use: + </para> + <refsect2 id="vboxmanage-controlvm-pause"> + <title>Pause a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> pause</command> command + temporarily stops the execution of a VM. When paused, the VM's + state is not permanently changed. + </para> + <para> + The VM window appears as gray and the title bar of the window + indicates that the VM is currently Paused. This action is + equivalent to selecting <emphasis role="bold">Pause</emphasis> + from the <emphasis role="bold">Machine</emphasis> menu of the + GUI. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-resume"> + <title>Resume a Paused Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> resume</command> command + restarts the execution of a paused VM. This action is equivalent + to selecting <emphasis role="bold">Resume</emphasis> from the + <emphasis role="bold">Machine</emphasis> menu of the GUI. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-reset"> + <title>Reset a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> reset</command> command + performs a cold reset the VM. This command has the same effect + on a VM as pressing the Reset button on a physical computer. + </para> + <para> + The cold reboot immediately restarts and reboots the guest + operating system (OS). The state of the VM is not saved prior to + the reset, so data might be lost. This action is equivalent to + selecting <emphasis role="bold">Reset</emphasis> from the + <emphasis role="bold">Machine</emphasis> menu of the GUI. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-poweroff"> + <title>Power Off a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> poweroff</command> command + powers off the VM. This command has the same effect on a VM as + pulling the power cable on a physical computer. + </para> + <para> + The state of the VM is not saved prior to poweroff, so data + might be lost. This action is equivalent to selecting + <emphasis role="bold">Close</emphasis> from the + <emphasis role="bold">Machine</emphasis> menu of the GUI or to + clicking the VM window's Close button, and then selecting + <emphasis role="bold">Power Off the Machine</emphasis>. + </para> + <para> + When in the powered off state, you can restart the VM. See + <xref linkend="vboxmanage-startvm" />. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-savestate"> + <title>Save the State of a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> savestate</command> command + saves the current state of the VM to disk and then stops the VM. + </para> + <para> + This action is equivalent to selecting + <emphasis role="bold">Close</emphasis> from the + <emphasis role="bold">Machine</emphasis> menu of the GUI or to + clicking the VM window's Close button, and then selecting + <emphasis role="bold">Save the Machine State</emphasis>. + </para> + <para> + When in the saved state, you can restart the VM. It will continue + exactly in the state you saved. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-acpipowerbutton"> + <title>Send an APCI Shutdown Signal to a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> acpipowerbutton</command> + command sends an ACPI shutdown signal to the VM. This command + has the same effect on a VM as pressing the Power button on a + physical computer. + </para> + <para> + So long as the VM runs a guest OS that provides appropriately + configured ACPI support, this command triggers an operating + system shutdown from within the VM. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-acpisleepbutton"> + <title>Send an APCI Sleep Signal to a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> acpisleepbutton</command> + command sends an ACPI sleep signal to the VM. + </para> + <para> + So long as the VM runs a guest OS that provides appropriately + configured ACPI support, this command triggers a sleep mechanism + from within the VM. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-reboot"> + <title>Reboot the guest OS</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> reboot</command> + command asks the guest OS to reboot itself. + </para> + <para> + This commands requires Guest Additions to be installed in the VM. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-shutdown"> + <title>Shut down the guest OS</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> shutdown</command> + command asks the guest OS to halt + shutdown, optionally forcing + the shutdown. + </para> + <para> + This commands requires Guest Additions to be installed in the VM. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-keyboardputscancode"> + <title>Send Keyboard Scancodes to a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> keyboardputscancode</command> + command sends keyboard scancode commands to the VM. + </para> + <para> + For information about keyboard scancodes, see + <ulink url="http://www.win.tue.nl/~aeb/linux/kbd/scancodes-1.html" />. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-keyboardputstring"> + <title>Send Keyboard Strings to a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> keyboardputstring</command> + command sends keyboard strings to the VM. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-keyboardputfile"> + <title>Send a File to a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> keyboardputfile</command> + command sends a file to the VM. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-setlinkstate"> + <title>Set the Link State for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + <command>VBoxManage controlvm <replaceable>vmname</replaceable> + setlinkstate<replaceable>N</replaceable></command> command + enables you to connect or disconnect the virtual network cable + from the network interface instance + (<replaceable>N</replaceable>). Valid values are + <literal>on</literal> and <literal>off</literal>. The default + value is <literal>on</literal>. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-nic"> + <title>Set the Type of Networking to Use for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> + nic<replaceable>N</replaceable></command> command specifies the + type of networking to use on the specified VM's virtual network + card. <replaceable>N</replaceable> numbering begins with + <literal>1</literal>. + </para> + <para> + The following valid network types are also described in + <xref linkend="networkingmodes" />: + </para> + <itemizedlist> + <listitem><para> + <literal>null</literal> specifies that the VM is is not + connected to the host system. + </para></listitem> + <listitem><para> + <literal>nat</literal> specifies that the VM uses network + address translation (NAT). + </para></listitem> + <listitem><para> + <literal>bridged</literal> specifies that the VM uses + bridged networking. + </para></listitem> + <listitem><para> + <literal>intnet</literal> specifies that the VM communicates + with other VMs by using internal networking. + </para></listitem> + <listitem><para> + <literal>hostonly</literal> specifies that the VM uses + host-only networking. + </para></listitem> + <listitem><para> + <literal>natnetwork</literal> specifies that the VM uses NAT + networking. + </para></listitem> + <listitem><para> + <literal>generic</literal> specifies that the VM has access + to rarely used submodes + </para></listitem> + </itemizedlist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-nictrace"> + <title>Trace the Network Traffic of a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> + nictrace<replaceable>N</replaceable></command> command enables + you to trace the network traffic on the specified virtual + network card (<replaceable>N</replaceable>). + <replaceable>N</replaceable> numbering begins with + <literal>1</literal>. Valid values are <literal>on</literal> and + <literal>off</literal>. The default value is + <literal>off</literal>. + </para> + <para> + If you did not configure a file name for the trace file then + a default one is used, placing it in the VM subdirectory. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-nictracefile"> + <title>Specify the Network Traffic Trace Log File for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> + nictracefile<replaceable>N</replaceable></command> command + enables you to specify the name of the network traffic trace log + file for the specified virtual network card + (<replaceable>N</replaceable>). <replaceable>N</replaceable> + numbering begins with <literal>1</literal>. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-nicpromisc"> + <title>Specify the Promiscuous Mode to Use for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> + nicpromisc<replaceable>N</replaceable></command> command enables + you to specify how to handle promiscuous mode for a bridged + network. The default value of <literal>deny</literal> hides any + traffic that is not intended for this VM. The + <literal>allow-vms</literal> value hides all host traffic from + this VM but enables the VM to see traffic to and from other VMs. + The <literal>allow-all</literal> value removes this restriction + completely. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-nicproperty"> + <title>Specify the Network Backend Property Values for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> + nicproperty<replaceable>N</replaceable> + <replaceable>prop-name</replaceable>=<replaceable>prop-value</replaceable></command> + command, in combination with <literal>nicgenericdrv</literal>, + enables you to pass property values to rarely-used network + backends. + </para> + <para> + Those properties are backend engine-specific, and are different + between UDP Tunnel and the VDE backend drivers. See + <xref linkend="network_udp_tunnel" />. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-natpf"> + <title>Specify a NAT Port Forwarding Rule for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> + natpf<replaceable>N</replaceable></command> command specifies a + NAT port-forwarding rule. See <xref linkend="natforward"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-natpf-delete"> + <title>Delete a NAT Port Forwarding Rule for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> + natpf<replaceable>N</replaceable> delete</command> command deletes + the specified NAT port-forwarding rule. See + <xref linkend="natforward"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-guestmemoryballoon"> + <title>Change Size of a Virtual Machine's Guest Memory Balloon</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> guestmemoryballoon</command> + command changes the size of the guest memory balloon. The guest + memory balloon is the memory allocated by the &product-name; + Guest Additions from the guest OS and returned to the hypervisor + for reuse by other VMs. The value you specify is in megabytes. + See <xref linkend="guestadd-balloon" />. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-usbattach"> + <title>Make a Host System USB Device Visible to a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> usbattach</command> command + dynamically attaches a host USB device to the VM, which makes it + visible. You do not need to create a filter. + </para> + <para> + Specify a USB device by its Universally Unique Identifier (UUID) + or by its address on the host system. Use the + <command>VBoxManage list usbhost</command> command to obtain + information about USB devices on the host system. + </para> + <para> + Use the <option>--capturefile</option> option to specify the + absolute path of a file in which to write logging data. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-usbdetach"> + <title>Make a Host System USB Device Invisible to a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> usbdetach</command> command + dynamically detaches a host USB device from the VM, which makes + it invisible. You do not need to create a filter. + </para> + <para> + Specify a USB device by its UUID or by its address on the host + system. Use the <command>VBoxManage list usbhost</command> + command to obtain information about USB devices on the host + system. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-audioin"> + <title>Enable or Disable Audio Capture From the Host System</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> audioin</command> command + specifies whether to enable or disable audio capture from the + host system. Valid values are <literal>on</literal>, which + enables audio capture and <literal>off</literal>, which disables + audio capture. The default value is <literal>off</literal>. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-audioout"> + <title>Enable or Disable Audio Playback From a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> audioout</command> command + specifies whether to enable or disable audio playback from the + guest VM. Valid values are <literal>on</literal>, which enables + audio playback and <literal>off</literal>, which disables audio + playback. The default value is <literal>off</literal>. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-clipboard-mode"> + <title>Specify How to Share the Host OS or Guest OS Clipboard</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> clipboard mode</command> command + specifies how to share the guest or host OS's clipboard with the + host system or VM. Valid values are <literal>disabled</literal>, + <literal>hosttoguest</literal>, <literal>guesttohost</literal>, + and <literal>bidirectional</literal>. The default value is + <literal>disabled</literal>. See + <xref linkend="generalsettings" />. + </para> + <para> + This feature requires that the &product-name; Guest Additions + are installed in the VM. + </para> + </refsect2> + + <refsect2 id="vboxmanage-controlvm-clipboard-filetransfers"> + <title>Specify If Files Can Be Transferred Through the Clipboard</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> clipboard filetransfers</command> + command specifies if it is possible to transfer files through the + clipboard between the host and VM, in the direction which is allowed. + Valid values are <literal>off</literal> and <literal>on</literal>. + The default value is <literal>off</literal>. + </para> + <para> + This feature requires that the &product-name; Guest Additions + are installed in the VM. + </para> + </refsect2> + + <refsect2 id="vboxmanage-controlvm-draganddrop"> + <title>Set the Drag and Drop Mode Between the Host System and a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> draganddrop</command> command + specifies the current drag and drop mode to use between the host + system and the VM. Valid values are <literal>disabled</literal>, + <literal>hosttoguest</literal>, <literal>guesttohost</literal>, + and <literal>bidirectional</literal>. The default value is + <literal>disabled</literal>. See + <xref linkend="guestadd-dnd" />. + </para> + <para> + This feature requires that the &product-name; Guest Additions + are installed in the VM. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-vrde"> + <title>Enable or Disable the VRDE Server</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> vrde</command> command enables + or disables the VirtualBox Remote Desktop Extension (VRDE) + server, if installed. Valid values are <literal>on</literal> and + <literal>off</literal>. The default value is + <literal>off</literal>. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-vrdeport"> + <title>Specify VRDE Server Ports</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> vrdeport</command> command + specifies the port or range of ports to which the VRDE server + can bind. The default value is <literal>default</literal> or + <literal>0</literal>, which is the standard RDP port, + <literal>3389</literal>. + </para> + <para> + Also see the <option>--vrde-port</option> option description in + <xref linkend="vboxmanage-modifyvm-vrde" />. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-vrdeproperty"> + <title>Specify VRDE Server Port Numbers and IP Addresses</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> vrdeproperty</command> command + specifies the port numbers and IP address on the VM to which the + VRDE server can bind. + </para> + <itemizedlist> + <listitem><para> + <literal>TCP/Ports</literal> specifies a port or a range of + ports to which the VRDE server can bind. The default value + is <literal>default</literal> or <literal>0</literal>, which + is the standard RDP port, <literal>3389</literal>. + </para><para> + Also see the <option>--vrde-port</option> option description + in <xref linkend="vboxmanage-modifyvm-vrde" />. + </para></listitem> + <listitem><para> + <literal>TCP/Address</literal> specifies the IP address of + the host network interface to which the VRDE server binds. + When specified, the server accepts to connect only on the + specified host network interface. + </para><para> + Also see the <option>--vrde-address</option> option + description in <xref linkend="vboxmanage-modifyvm-vrde" />. + </para></listitem> + <listitem><para> + <literal>VideoChannel/Enabled</literal> specifies whether to + enable the VirtualBox Remote Desktop Protocol (VRDP) video + channel. Valid values are <literal>1</literal> to enable the + video channel and <literal>0</literal> to disable the video + channel. The default value is <literal>off</literal>. See + <xref linkend="vrde-videochannel" />. + </para></listitem> + <listitem><para> + <literal>VideoChannel/Quality</literal> specifies the JPEG + compression level on the VRDE server video channel. Valid + values are between 10% and 100%, inclusive. Lower values + mean lower quality but higher compression. The default value + is <literal>100</literal>. See + <xref linkend="vrde-videochannel" />. + </para></listitem> + <listitem><para> + <literal>VideoChannel/DownscaleProtection</literal> + specifies whether to enable the video channel downscale + protection feature. Specify <literal>1</literal> to enable + the feature. This feature is disabled by default. + </para><para> + When enabled, if the video's size equals the shadow buffer + size, the video is shown in full-screen mode. If the video's + size is between full-screen mode and the downscale + threshold, the video is not shown as it might be an + application window that is unreadable when downscaled. When + disabled, the downscale protection feature always attempts + to show videos. + </para></listitem> + <listitem><para> + <literal>Client/DisableDisplay</literal> specifies whether + to disable the VRDE server display feature. Valid values are + <literal>1</literal> to disable the feature and an empty + string (<literal>""</literal>) to enable the feature. + The default value is an empty string. See + <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>Client/DisableInput</literal> specifies whether to + disable the VRDE server input feature. Valid values are + <literal>1</literal> to disable the feature and an empty + string (<literal>""</literal>) to enable the feature. + The default value is <literal>1</literal>. See + <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>Client/DisableAudio</literal> specifies whether to + disable the VRDE server audio feature. Valid values are + <literal>1</literal> to disable the feature and an empty + string (<literal>""</literal>) to enable the feature. + The default value is <literal>1</literal>. See + <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>Client/DisableUSB</literal> specifies whether to + disable the VRDE server USB feature. Valid values are + <literal>1</literal> to disable the feature and an empty + string (<literal>""</literal>) to enable the feature. + The default value is <literal>1</literal>. See + <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>Client/DisableClipboard</literal> specifies whether + to disable the VRDE clipboard feature. Valid values are + <literal>1</literal> to disable the feature and an empty + string (<literal>""</literal>) to enable the feature. + To reenable the feature, use + <literal>Client/DisableClipboard=</literal>. The default + value is <literal>1</literal>. See + <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>Client/DisableUpstreamAudio</literal> specifies + whether to disable the VRDE upstream audio feature. Valid + values are <literal>1</literal> to disable the feature and + an empty string (<literal>""</literal>) to enable the + feature. To reenable the feature, use + <literal>Client/DisableUpstreamAudio=</literal>. The default + value is <literal>1</literal>. See + <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>Client/DisableRDPDR</literal> specifies whether to + disable the RDP Device Redirection For Smart Cards feature + on the VRDE server. Valid values are <literal>1</literal> to + disable the feature and an empty string + (<literal>""</literal>) to enable the feature. + The default value is <literal>1</literal>. See + <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>H3DRedirect/Enabled</literal> specifies whether to + enable the VRDE server 3D redirection feature. Valid values + are <literal>1</literal> to enable the feature and an empty + string (<literal>""</literal>) to disable the feature. + See <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>Security/Method</literal> specifies the security + method to use for a connection. See + <xref linkend="vrde-crypt" />. + </para><itemizedlist> + <listitem><para> + <literal>Negotiate</literal> accepts both enhanced (TLS) + and standard RDP security connections. The security + method is negotiated with the client. This is the + default value. + </para></listitem> + <listitem><para> + <literal>RDP</literal> accepts only standard RDP + security connections. + </para></listitem> + <listitem><para> + <literal>TLS</literal> accepts only enhanced RDP + security connections. The client must support TLS. + </para></listitem> + </itemizedlist></listitem> + <listitem><para> + <literal>Security/ServerCertificate</literal> specifies the + absolute path of the server certificate to use for a + connection. See <xref linkend="vrde-crypt" />. + </para></listitem> + <listitem><para> + <literal>Security/ServerPrivateKey</literal> specifies the + absolute path of the server private key. See + <xref linkend="vrde-crypt" />. + </para></listitem> + <listitem><para> + <literal>Security/CACertificate</literal> specifies the + absolute path of the CA self-signed certificate. See + <xref linkend="vrde-crypt" />. + </para></listitem> + <listitem><para> + <literal>Audio/RateCorrectionMode</literal> specifies the + rate correction mode to use. + </para><itemizedlist> + <listitem><para> + <literal>VRDP_AUDIO_MODE_VOID</literal> indicates that + no mode is specified. Use this value to unset any audio + mode that is already set. + </para></listitem> + <listitem><para> + <literal>VRDP_AUDIO_MODE_RC</literal> specifies to use + the rate correction mode. + </para></listitem> + <listitem><para> + <literal>VRDP_AUDIO_MODE_LPF</literal> specifies to use + the low pass filter mode. + </para></listitem> + <listitem><para> + <literal>VRDP_AUDIO_MODE_CS</literal> specifies to use + the client sync mode to prevent underflow or overflow of + the client queue. + </para></listitem> + </itemizedlist></listitem> + <listitem><para> + <literal>Audio/LogPath</literal> specifies the absolute path + of the audio log file. + </para></listitem> + </itemizedlist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-vrdevideochannelquality"> + <title>Specify the Image Quality for VRDP Video Redirection</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> + vrdevideochannelquality</command> command sets the image + quality, as a JPEG compression level value, for video + redirection. Valid values are between 10% and 100%, inclusive. + Lower values mean lower quality but higher compression. See + <xref linkend="vrde-videochannel" />. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-setvideomodehint"> + <title>Specify the Video Mode for the Guest VM</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> setvideomodehint</command> + command specifies the video mode for the guest VM to use. You + must have the &product-name; Guest Additions installed. Note + that this feature does not work for all guest systems. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-setscreenlayout"> + <title>Specify the Screen Layout for a Display on the Guest VM</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> setscreenlayout</command> + command can be used to configure multiscreen displays. The + specified screen on the guest VM can be enabled or disabled, or + a custom screen layout can be configured. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-screenshotpng"> + <title>Take a Screen Shot of the Virtual Machine Display</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> screenshotpng</command> + command takes a screenshot of the guest display and saves it as + PNG in the specified file. + </para> + <itemizedlist> + <listitem><para> + <replaceable>filename</replaceable> specifies the name of + the PNG file to create. + </para></listitem> + <listitem><para> + <replaceable>display</replaceable> specifies the display + number for the screen shot. For a single monitor guest + display, this is <literal>0</literal>. + </para></listitem> + </itemizedlist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording"> + <title>Enable or Disable the Recording of a Virtual Machine Session</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> recording</command> command + enables or disables the recording of a VM session into a + WebM/VP8 file. Valid values are <literal>on</literal>, which + begins recording when the VM session starts and + <literal>off</literal>, which disables recording. The default + value is <literal>off</literal>. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording-screens"> + <title>Specify the Virtual Machine Screens to Record</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> recording screens</command> + command enables you to specify which VM screens to record. The + recording for each screen that you specify is saved to its own + file in the machine folder. You cannot modify this setting while + recording is enabled. + </para> + <itemizedlist> + <listitem><para> + <literal>all</literal> specifies that you record all VM + screens. + </para></listitem> + <listitem><para> + <literal>none</literal> specifies that you do not record any + VM screens. + </para></listitem> + <listitem><para> + <replaceable>screen-ID</replaceable> specifies one or more + VM screens to record. + </para></listitem> + </itemizedlist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording-filename"> + <title>Specify the File in Which to Save Virtual Machine Recording</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> recording filename</command> + command specifies the file in which to save the recording. You + cannot modify this setting while recording is enabled. + </para> + <para> + The default setting is to store a recording in the machine + folder, using the VM name as the file name, with a + <filename>webm</filename> file name extension. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording-videores"> + <title>Specify the Resolution of the Recorded Video</title> + <remark role="help-copy-synopsis"/> + <para> + <command>VBoxManage controlvm <replaceable>vmname</replaceable> + recording videores</command> command specifies the resolution of + the recorded video in pixels. You cannot modify this setting + while recording is enabled. + </para> + <para> + Use the Settings tool to view the video recording settings, + which are based on the resolution (frame size). See the Frame + Size field on the Recording tab of the Display page to view the + default value. + </para> + <para> + Specify the resolution as + <replaceable>width</replaceable><literal>x</literal><replaceable>height</replaceable>: + </para> + <itemizedlist> + <listitem><para> + <replaceable>width</replaceable> specifies the width in + pixels. + </para></listitem> + <listitem><para> + <replaceable>height</replaceable> specifies the height in + pixels. + </para></listitem> + </itemizedlist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording-videorate"> + <title>Specify the Bit Rate of the Video</title> + <remark role="help-copy-synopsis"/> +<!-- @todo r=andy Clarify rate. --> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> recording videorate</command> + command specifies the bit rate, + <replaceable>bit-rate</replaceable>, of the video in kilobits + per second. Increasing this value improves the appearance of the + video at the cost of an increased file size. You cannot modify + this setting while recording is enabled. + </para> + <para> + Use the Settings tool to view the video recording settings, + which are based on the frame size. See the Video Quality field + on the Recording tab of the Display page to view the default + value. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording-videofps"> + <title>Specify the Maximum Frequency of the Video</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> recording videofps</command> + command specifies the maximum frequency of the video to record. + Video frequency is measured in frames per second (FPS). The + recording skips any frames that have a frequency higher than the + specified maximum. Increasing the frequency reduces the number + of skipped frames and increases the file size. You cannot modify + this setting while recording is enabled. + </para> + <para> + Use the Settings tool to view the video recording settings, + which are based on the frame size. See the Frame Rate field on + the Recording tab of the Display page to view the default value. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording-maxtime"> + <title>Specify the Maximum Amount of Time to Record Video</title> + <remark role="help-copy-synopsis"/> +<!-- @todo r=andy Clarify time format. --> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> recording maxtime</command> + command specifies the maximum amount time to record in seconds. + The recording stops after the specified number of seconds + elapses. If this value is zero, the recording continues until + you stop the recording. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording-maxfilesize"> + <title>Specify the Maximum Size of the Recorded Video</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> recording + maxfilesize</command> command specifies the maximum size of the + recorded video file in megabytes. The recording stops when the + file reaches the specified size. If this value is zero, the + recording continues until you stop the recording. You cannot + modify this setting while recording is enabled. + </para> + </refsect2> + <!-- + <refsect2 id="vboxmanage-controlvm-recording-opts"> + <title>Specify Custom Options for Recording Video and/or Audio</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> recording + opts</command> command specifies additional recording options + in a comma-separated keyword-value format. For example, + <computeroutput>foo=bar,a=b</computeroutput>. You cannot + modify this setting while recording is enabled. + </para> + <para> + Use this option if you are an advanced user only. For + information about keywords, see <emphasis>&product-name; + Programming Guide and Reference</emphasis>. + </para> + </refsect2> + --> + <refsect2 id="vboxmanage-controlvm-setcredentials"> + <title>Specify Credentials for Remote Logins on Windows Virtual Machines</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>setcredentials</command> command enables you to + specify the credentials for remotely logging in to Windows VMs. + See <xref linkend="autologon" />. + </para> + <itemizedlist> + <listitem><para> + <replaceable>username</replaceable> specifies the user name + with which to log in to the Windows VM. + </para></listitem> + <listitem><para> + <option>--passwordfile=<replaceable>filename</replaceable></option> + specifies the file from which to obtain the password for + <replaceable>username</replaceable>. + </para><para> + The <option>--passwordfile</option> is mutually exclusive + with the <option>--password</option> option. + </para></listitem> + <listitem><para> + <option>--password=<replaceable>password</replaceable></option> + specifies the password for + <replaceable>username</replaceable>. + </para><remark> + This design does not conform to Oracle's security + guidelines. You should not be able to specify a password on + the command line because the password can be seen in a + process listing. + </remark><para> + The <option>--password</option> is mutually exclusive with + the <option>--passwordfile</option> option. + </para></listitem> + <listitem><para> + <option>--allowlocallogin</option> specifies whether to + enable or disable local logins. Valid values are + <literal>on</literal> to enable local logins and + <literal>off</literal> to disable local logins. + </para></listitem> + </itemizedlist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-teleport"> + <title>Configure a Virtual Machine Target for Teleporting</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> teleport</command> command + initiates a teleporting operation between the specified VM and + the specified host system. See <xref linkend="teleporting" />. + </para> + <para> + If you specify a password, it must match the password you + specified when you issued the <command>VBoxManage + modifyvm</command> command for the target machine. + </para> + <variablelist> + <varlistentry> + <term><option>--host=<replaceable>hostname</replaceable></option></term> + <listitem><para> + Specifies the name of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--port=<replaceable>port</replaceable></option></term> + <listitem><para> + Specifies the port on the VM that should listen for a + teleporting request from other VMs. The port number can be + any free TCP/IP port number, such as + <literal>6000</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--maxdowntime=<replaceable>msec</replaceable></option></term> + <listitem><para> + Specifies the maximum downtime, in milliseconds, for the + teleporting target VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password=<replaceable>password</replaceable></option></term> + <listitem><para> + Specifies the password that the source machine uses for + the teleporting request. The request succeeds only if the + source machine specifies the same password. + </para><remark> + This design does not conform to Oracle's security + guidelines. You should not be able to specify a password + on the command line because the password can be seen in a + process listing. + </remark><para> + The <option>--password</option> is mutually exclusive with + the <option>--passwordfile</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--passwordfile=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies the file from which to obtain the password that + the source machine uses for the teleporting request. The + request succeeds only if the source machine specifies the + same password. + </para><para> + When you specify a file name of <literal>stdin</literal>, + you can read the password from standard input. + </para><para> + The <option>--passwordfile</option> is mutually exclusive + with the <option>--password</option> option. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-plugcpu"> + <title>Add a Virtual CPU to a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> plugcpu</command> command adds + a virtual CPU to the specified VM if CPU hot-plugging is + enabled. <replaceable>ID</replaceable> specifies the index of + the virtual CPU to be added and must be a number from 0 to the + maximum number of CPUs configured. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-unplugcpu"> + <title>Remove a Virtual CPU From a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> unplugcpu</command> command + removes a virtual CPU from the specified VM if CPU hot-plugging + is enabled. <replaceable>ID</replaceable> specifies the index of + the virtual CPU to be removed and must be a number from 0 to the + maximum number of CPUs configured. You cannot remove CPU 0. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-cpuexecutioncap"> + <title>Set the Maximum Amount of Physical CPU Time Used by a Virtual CPU</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> cpuexecutioncap</command> + command specifies how the maximum amount of physical CPU time + used by a virtual CPU. Valid values are a percentage between + <literal>1</literal> and <literal>100</literal>. A value of + <literal>50</literal> specifies that a single virtual CPU can + use up to 50% of a physical CPU. The default value is + <literal>100</literal>. + </para> + <para> + Use this feature with caution, it can have unexpected results + including timekeeping problems and lower performance than + specified. If you want to limit the resource usage of a VM + it is more reliable to pick an appropriate number of VCPUs. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-vm-process-priority"> + <title>Change the Priority of a VM Process</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> vm-process-priority</command> + command specifies the priority scheme of the VM process to use + when starting the specified VM and while the VM runs. + </para> + <para> + Valid values are: + </para> + <itemizedlist> + <listitem><para> + <literal>default</literal> – Default process + priority determined by the OS. + </para></listitem> + <listitem><para> + <literal>flat</literal> – Assumes a scheduling + policy which puts the process at the default priority + and with all threads at the same priority. + </para></listitem> + <listitem><para> + <literal>low</literal> – Assumes a scheduling + policy which puts the process mostly below the default + priority of the host OS. + </para></listitem> + <listitem><para> + <literal>normal</literal> – Assume a scheduling + policy which shares the CPU resources fairly with + other processes running with the default priority of + the host OS. + </para></listitem> + <listitem><para> + <literal>high</literal> – Assumes a scheduling + policy which puts the task above the default priority of + the host OS. This policy might easily cause other tasks + in the system to starve. + </para></listitem> + </itemizedlist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-webcam-attach"> + <title>Attach a Webcam to a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> webcam attach</command> + command attaches a webcam to a running VM. Specify the webcam as + the absolute path of the webcam on the host OS or as an alias. + Use the <command>VBoxManage list webcams</command> command to + obtain the webcam alias. + </para> + <para> + Note that the <literal>.0</literal> alias is the default video + input device on the host OS. <literal>.1</literal> is the first + video input device, <literal>.2</literal> is the second video + input device, and so on. The order of the devices is specific to + the host system. + </para> + <para> + You can specify optional settings in the form of + semi-colon-separated (<literal>;</literal>) name-value pairs. + These properties enable you to configure the emulated webcam + device. + </para> + <para> + The following settings are supported: + </para> + <variablelist> + <varlistentry> + <term><literal>MaxFramerate</literal></term> + <listitem><para> + Specifies the highest rate at which to send video frames + to the VM. The rate is in frames per second. Higher frame + rates increase CPU load, so you can use this setting to + reduce CPU load. The default value is <literal>no maximum + limit</literal>. This value enables the VM to use any + frame rate supported by the webcam. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>MaxPayloadTransferSize</literal></term> + <listitem><para> + Specifies the maximum number of bytes that the VM receives + from the emulated webcam in one buffer. The default + setting is <literal>3060</literal> bytes, which is used by + some webcams. If the VM is able to use larger buffers, + higher values might reduce CPU load slightly. Note that + some guest OSes might not suppport higher + <literal>MaxPayloadTransferSize</literal> values. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-webcam-detach"> + <title>Detach a Webcam From a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> webcam detach</command> + command detaches a webcam from a running VM. Specify the webcam + as the absolute path of the webcam on the host OS or as an + alias. Use the <command>VBoxManage list webcams</command> to + obtain the webcam alias. + </para> + <para> + When a webcam device is detached from the host, the host OS + determines how the emulated webcam behaves. + </para> + <itemizedlist> + <listitem><para> + <emphasis role="bold">Windows hosts:</emphasis> The emulated + webcam device is detached from the VM automatically. + </para></listitem> + <listitem><para> + <emphasis role="bold">Mac OS X hosts that run at least OS X + 10.7:</emphasis> The emulated webcam device remains attached + to the VM and you must detach it manually by using the + <command>VBoxManage controlvm webcam detach</command> + command. + </para></listitem> + <listitem><para> + <emphasis role="bold">Linux hosts:</emphasis> The emulated + webcam device is detached from the VM automatically only if + the webcam is actively streaming video. If the emulated + webcam is inactive, manually detach it by using the + <command>VBoxManage controlvm + <replaceable>vmname</replaceable> webcam detach</command> + command. + </para></listitem> + </itemizedlist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-webcam-list"> + <title>List the Webcams Attached to a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> webcam list</command> command + lists webcams that are attached to the running VM. The output + shows a list of absolute paths or aliases that attached the + webcams to the VM by using the <command>VBoxManage controlvm + <replaceable>vmname</replaceable> webcam attach</command> + command. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-addencpassword"> + <title>Set an Encryption Password for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> addencpassword</command> + command provides the <replaceable>vmname</replaceable> encrypted + VM with the encryption password to enable a headless start. + Specify the absolute path of a password file on the host system. + If <replaceable>filename</replaceable> is <literal>-</literal>, + <command>VBoxManage</command> prompts for the encryption + password. + </para> + <para> + Use the <option>--removeonsuspend</option> option to specify + whether to save the passsword or clear it from VM memory when + the VM is suspended. + </para> + <para> + If the VM is suspended and the password is cleared, use the + <command>VBoxManage controlvm <replaceable>vmname</replaceable> + addencpassword</command> to provide the password to resume + execution on the VM. Use this feature when you do not want to + store the password in VM memory while the VM is suspended by a + host suspend event. + </para> + <note> + <para> + You can encrypt data stored on hard disk images used by the + VM. &product-name; uses the AES algorithm in XTS mode and + supports 128-bit or 256-bit data encryption keys (DEK). The + encrypted DEK is stored in the medium properties and is + decrypted during VM startup when you provide the encryption + password. + </para> + </note> + <para> + Use the <command>VBoxManage encryptmedium</command> command to + create a DEK encrypted medium. See + <xref linkend="diskencryption-encryption" />. + </para> + <para> + The &product-name; GUI prompts you for the encryption password + when you start an encrypted VM. + </para> + <para> + Use the following command to perform a headless start of an + encrypted VM: + </para> +<screen> + $ VBoxManage startvm <replaceable>vmname</replaceable> --type headless + </screen> + <para> + Then, use the following command to provide the encryption + password: + </para> +<screen> + $ VBoxManage <replaceable>vmname</replaceable> controlvm addencpassword <replaceable>vmname</replaceable> - + Password: <replaceable>encryption-password</replaceable> + </screen> + </refsect2> + <refsect2 id="vboxmanage-controlvm-removeencpassword"> + <title>Disable an Encryption Password for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> removeencpassword</command> + command disables a specific encryption password for all + encrypted media attached to the VM. + </para> + <para> + <replaceable>ID</replaceable> is the password identifier for the + encryption password that you want to disable. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-removeallencpasswords"> + <title>Disable All Encryption Passwords for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> + removeallencpasswords</command> command disables all encryption + passwords for all encrypted media attached to the VM. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-changeuartmode"> + <title>Change the Connection Mode for a Virtual Serial Port on a Virtual + Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> changeuartmode</command> + command changes the connection mode for the specified virtual + serial port. Valid serial port values are integers that start + from <literal>1</literal>. + </para> + <variablelist> + <varlistentry> + <term>disconnected</term> + <listitem><para> + Disconnects the device. + </para></listitem> + </varlistentry> + <varlistentry> + <term>server <replaceable>pipe-name</replaceable></term> + <listitem><para> + Specifies the pipe name of the server. + </para></listitem> + </varlistentry> + <varlistentry> + <term>client <replaceable>pipe-name</replaceable></term> + <listitem><para> + Specifies the pipe name of the client. + </para></listitem> + </varlistentry> + <varlistentry> + <term>tcpserver <replaceable>port</replaceable></term> + <listitem><para> + Specifies the port number of the TCP server. + </para></listitem> + </varlistentry> + <varlistentry> + <term>tcpclient <replaceable>hostname</replaceable>:<replaceable>port</replaceable></term> + <listitem><para> + Specifies the host name and port number of the TCP client. + </para></listitem> + </varlistentry> + <varlistentry> + <term>file <replaceable>filename</replaceable></term> + <listitem><para> + Specifies the name of the file. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>device-name</replaceable></term> + <listitem><para> + Specifies the name of the device. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-autostart-enabled"> + <title>Enabling autostart the VM during host system boot</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> autostart-enabled</command> + command specifies whether to enable or disable automatically + start the VM at host system boot-up. You must do some host + system configuration before you can use this feature. + See <xref linkend="autostart" />. Valid values are + <literal>on</literal>, which enables autostart feature for + the VM and <literal>off</literal>, which disables it. The + default value is <literal>off</literal>. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-autostart-delay"> + <title>Setting the delay of starting the VM on host system boot</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> autostart-delay</command> + command specifies the delay in seconds before the VM starts + on host system boot-up. See <xref linkend="autostart" />. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command temporarily stops the execution of the + <filename>ol7</filename> VM. + </para> +<screen>$ VBoxManage controlvm ol7 pause</screen> + <para> + The following command configures shared clipboard operation for + the <filename>ol7</filename> VM. Copying of clipboard data is + allowed in both directions between the host and guest. + </para> +<screen>$ VBoxManage controlvm ol7 clipboard mode bidirectional</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-list" />, + <xref linkend="vboxmanage-modifyvm" />, + <xref linkend="vboxmanage-startvm" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-convertfromraw.xml b/doc/manual/en_US/man_VBoxManage-convertfromraw.xml new file mode 100644 index 00000000..84bd59cf --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-convertfromraw.xml @@ -0,0 +1,266 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage convertfromraw +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-convertfromraw" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-05-30 22:24:41 +0200 (Tue, 30 May 2023) $</pubdate> + <title>VBoxManage convertfromraw</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-convertfromraw</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-convertfromraw</refname> + <refpurpose>convert a raw disk image to a virtual disk image</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <cmdsynopsis id="synopsis-vboxmanage-convertfromraw-file"> + <command>VBoxManage convertfromraw</command> + <arg choice="req"><replaceable>inputfile</replaceable></arg> + <arg choice="req"><replaceable>outputfile</replaceable></arg> + <arg>--format=<group choice="plain"> + <arg choice="plain">VDI</arg> + <arg choice="plain">VMDK</arg> + <arg choice="plain">VHD</arg> + </group></arg> + <arg>--uuid=<replaceable>uuid</replaceable></arg> + <arg>--variant=Standard,Fixed,Split2G,Stream,ESX</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-convertfromraw-stdin"> + <command>VBoxManage convertfromraw stdin</command> + <arg choice="req"><replaceable>outputfile</replaceable></arg> + <arg choice="req"><replaceable>bytes</replaceable></arg> + <arg>--format=<group choice="plain"> + <arg choice="plain">VDI</arg> + <arg choice="plain">VMDK</arg> + <arg choice="plain">VHD</arg> + </group></arg> + <arg>--uuid=<replaceable>uuid</replaceable></arg> + <arg>--variant=Standard,Fixed,Split2G,Stream,ESX</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage convertfromraw</command> command enables + you to convert a raw disk image to an &product-name; virtual disk + image (VDI). + </para> + <note> + <para> + For compatibility with earlier versions of &product-name;, you + can use the <command>VBoxManage convertdd</command> command + instead of the <command>VBoxManage convertfromraw</command> + command. + </para> + </note> + <refsect2 id="vboxmanage-convertfromraw-file"> + <title>Convert a Raw Disk File to a Virtual Disk Image File</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage convertfromraw</command> command + converts the specified raw disk image input file to an + &product-name; VDI file. + </para> + <variablelist> + <varlistentry> + <term><replaceable>inputfile</replaceable></term> + <listitem><para> + Specifies the name of the raw disk image file to convert. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>outputfile</replaceable></term> + <listitem><para> + Specifies the name of the file in which to write the VDI + output. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--format=VDI | VMDK | VHD</option></term> + <listitem><para> + Specifies the format of the disk image to create. Valid + values are <literal>VDI</literal>, + <literal>VMDK</literal>, and <literal>VHD</literal>. The + default format is <literal>VDI</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) of the + output file. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--variant=Standard,Fixed,Split2G,Stream,ESX</option></term> + <listitem><para> + Specifies any required file format variants for the output + file. This is a comma-separated list of variant values. + Following are the valid values: + </para><itemizedlist> + <listitem><para> + <literal>Standard</literal> is the default disk image + type, which has a dynamically allocated file size. + </para></listitem> + <listitem><para> + <literal>Fixed</literal> uses a disk image that has a + fixed file size. + </para></listitem> + <listitem><para> + <literal>Split2G</literal> indicates that the disk + image is split into 2GB segments. This value is for + VMDK only. + </para></listitem> + <listitem><para> + <literal>Stream</literal> optimizes the disk image for + downloading. This value is for VMDK only. + </para></listitem> + <listitem><para> + <literal>ESX</literal> is used for some VMWare + products. This value is for VMDK only. + </para></listitem> + </itemizedlist><para> + Note that not all variant combinations are valid. + Specifying incompatible variant values in the list will + produce an error message. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-convertfromraw-stdin"> + <title>Convert Raw Data From Standard Input to a Virtual Disk Image File</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage convertfromraw stdin</command> command + reads the content of the disk image from standard input. + Consider using this form of the command in a pipe sequence. + </para> + <variablelist> + <varlistentry> + <term><replaceable>outputfile</replaceable></term> + <listitem><para> + Specifies the name of the file in which to write the disk image + output. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>bytes</replaceable></term> + <listitem><para> + Specifies the capacity of the targe image name. Needs to be + given explicitly, because generally pipes do not support + querying the overall size of the data stream. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--format=VDI | VMDK | VHD</option></term> + <listitem><para> + Specifies the format of the disk image to create. Valid + values are <literal>VDI</literal>, + <literal>VMDK</literal>, and <literal>VHD</literal>. The + default format is <literal>VDI</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Specifies the UUID of the output file. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--variant=Standard,Fixed,Split2G,Stream,ESX</option></term> + <listitem><para> + Specifies any required file format variants for the output + file. This is a comma-separated list of variant values. + Following are the valid values: + </para><itemizedlist> + <listitem><para> + <literal>Standard</literal> is the default disk image + type, which has a dynamically allocated file size. + </para></listitem> + <listitem><para> + <literal>Fixed</literal> uses a disk image that has a + fixed file size. + </para></listitem> + <listitem><para> + <literal>Split2G</literal> indicates that the disk + image is split into 2GB segments. This value is for + VMDK only. + </para></listitem> + <listitem><para> + <literal>Stream</literal> optimizes the disk image for + downloading. This value is for VMDK only. + </para></listitem> + <listitem><para> + <literal>ESX</literal> is used for some VMWare + products. This value is for VMDK only. + </para></listitem> + </itemizedlist><para> + Note that not all variant combinations are valid. + Specifying incompatible variant values in the list will + produce an error message. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command converts the raw disk image input file + <filename>disk01.raw</filename>. The output file is a VDI disk + image called <filename>disk02.vdi</filename>. + </para> +<screen>$ VBoxManage convertfromraw disk01.raw disk02.vdi</screen> + <para> + The following command converts the raw disk image input file + <filename>disk01.raw</filename>. The output file is a VMDK disk + image called <filename>disk02.vmdk</filename>. + </para> +<screen>$ VBoxManage convertfromraw disk01.raw disk02.vmdk --format VMDK</screen> + <para> + The following command reads from disk <filename>/dev/sda</filename> + using a pipe and therefore needs the exact disk size in bytes as an + additional parameter, which is assumed to be <literal>10737418240</literal>. + The output file is a VDI disk image called <filename>disk.vdi</filename>. + </para> +<screen>$ dd if=/dev/sda bs=512 | VBoxManage convertfromraw stdin disk.vdi 10737418240</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-createmedium.xml b/doc/manual/en_US/man_VBoxManage-createmedium.xml new file mode 100644 index 00000000..71fdd848 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-createmedium.xml @@ -0,0 +1,224 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage createmedium +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-createmedium" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage createmedium</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-createmedium</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-createmedium</refname> + <refpurpose>create a new medium</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-createmedium"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage createmedium</command> + <group> + <arg choice="plain"><replaceable>disk</replaceable></arg> + <arg choice="plain"><replaceable>dvd</replaceable></arg> + <arg choice="plain"><replaceable>floppy</replaceable></arg> + </group> + <arg choice="req">--filename=<replaceable>filename</replaceable></arg> + <group> + <arg choice="plain">--size=<replaceable>megabytes</replaceable></arg> + <arg choice="plain">--sizebyte=<replaceable>bytes</replaceable></arg> + </group> + <arg>--diffparent=<group choice="plain"> + <arg choice="plain"><replaceable>UUID</replaceable></arg> + <arg choice="plain"><replaceable>filename</replaceable></arg> + </group></arg> + <arg>--format=<group choice="plain"> + <arg choice="plain"><replaceable>VDI</replaceable></arg> + <arg choice="plain"><replaceable>VMDK</replaceable></arg> + <arg choice="plain"><replaceable>VHD</replaceable></arg> + </group></arg> + <arg>--variant Standard,Fixed,Split2G,Stream,ESX,Formatted,RawDisk</arg> + <arg choice="plain" rep="repeat">--property + <replaceable>name</replaceable>=<replaceable>value</replaceable></arg> + <arg choice="plain" rep="repeat">--property-file + <replaceable>name</replaceable>=<replaceable>/path/to/file/with/value</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage createmedium</command> command creates a + new medium, such as a disk image file. + </para> + <note> + <para> + For compatibility with earlier versions of &product-name;, you + can use the <command>createvdi</command> and + <command>createhd</command> commands instead of the + <command>createmedium</command> command. + </para> + </note> + <variablelist> + <varlistentry> + <term>disk | dvd | floppy</term> + <listitem><para> + Specifies the media type. The default value is + <literal>disk</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--filename=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies the absolute path name to a file on the host file + system. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--size=<replaceable>megabytes</replaceable></option></term> + <listitem><para> + Specifies the image capacity in one megabyte units. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--sizebyte=<replaceable>bytes</replaceable></option></term> + <listitem><para> + Specifies the image capacity in one byte units. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--diffparent=<replaceable>UUID</replaceable> | <replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or + absolute path name of a differencing image parent file on + the host file system. + </para><para> + Use this file to share a base box disk image among VMs. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--format=VDI | VMDK | VHD</option></term> + <listitem><para> + Specifies the file format of the output file. Valid formats + are <literal>VDI</literal>, <literal>VMDK</literal>, and + <literal>VHD</literal>. The default format is + <literal>VDI</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--variant=Standard,Fixed,Split2G,Stream,ESX,Formatted,RawDisk</option></term> + <listitem><para> + Specifies the file format variant for the target medium, + which is a comma-separated list of variants. Following are + the valid values: + </para><itemizedlist> + <listitem><para> + <literal>Standard</literal> is the default disk image + type, which has a dynamically allocated file size. + </para></listitem> + <listitem><para> + <literal>Fixed</literal> uses a disk image that has a + fixed file size. + </para></listitem> + <listitem><para> + <literal>Split2G</literal> indicates that the disk image + is split into 2GB segments. This value is valid for VMDK + disk images only. + </para></listitem> + <listitem><para> + <literal>Stream</literal> optimizes the disk image for + downloading. This value is valid for VMDK disk images + only. + </para></listitem> + <listitem><para> + <literal>ESX</literal> is used for some VMWare products. + This value is valid for VMDK disk images only. + </para></listitem> + <listitem><para> + <literal>Formatted</literal> formats the medium automatically. + This value is valid for floppy images only. + </para></listitem> + <listitem><para> + <literal>RawDisk</literal> is used for creating a VMDK + image which provides direct access to the hard disk on + the host using its raw interface. This value is valid for + VMDK disk images only. For detailed information about raw + disk access, see <xref linkend="adv-storage-config"/>. + </para></listitem> + </itemizedlist><para> + Note that not all variant combinations are valid. Specifying + incompatible variant values in the list will produce an + error message. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--property <replaceable>name</replaceable>=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies any required file format dependent parameters in + <literal>key=value</literal> form. Optional. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--property-file <replaceable>name + </replaceable>=<replaceable>/path/to/file/with/value</replaceable></option></term> + <listitem><para> + Specifies any required file format dependent parameters in + <literal>key=file/with/value</literal> form. The value is + taken from the file. Optional. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command creates a new disk image file named + <filename>disk01.vdi</filename>. The file size is 1024 megabytes. + </para> +<screen>$ VBoxManage createmedium --filename disk01.vdi --size 1024</screen> + <para> + The following command creates a new floppy disk image file named + <filename>floppy01.vdi</filename>. The file size is 1 megabyte. + </para> +<screen>$ VBoxManage createmedium floppy --filename floppy01.img --size 1</screen> + <para> + The following command creates a raw disk image of an entire physical disk + on a Linux host. + </para> + <screen>$ VBoxManage createmedium disk --filename=/path/to/rawdisk.vmdk --variant=RawDisk --format=VMDK --property RawDrive=/dev/sda</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-createvm.xml b/doc/manual/en_US/man_VBoxManage-createvm.xml new file mode 100644 index 00000000..dea674a6 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-createvm.xml @@ -0,0 +1,210 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage createvm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-createvm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage createvm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-createvm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-createvm</refname> + <refpurpose>create a new virtual machine</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-createvm"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage createvm</command> + <arg choice="req">--name=<replaceable>name</replaceable></arg> + <arg>--basefolder=<replaceable>basefolder</replaceable></arg> + <arg>--default</arg> + <arg>--group=<replaceable>group-ID</replaceable>,...</arg> + <arg>--ostype=<replaceable>ostype</replaceable></arg> + <arg>--register</arg> + <arg>--uuid=<replaceable>uuid</replaceable></arg> + <arg>--cipher <replaceable>cipher</replaceable></arg> + <arg>--password-id <replaceable>password-id</replaceable></arg> + <arg>--password <replaceable>file</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage createvm</command> command creates a new + XML virtual machine (VM) definition file. + </para> + <para> + You must specify the name of the VM by using <option>--name + <replaceable>name</replaceable></option>. This name is used by + default as the name of the settings file that has the + <filename>.vbox</filename> extension and the machine folder, which + is a subfolder of the <filename>$HOME/VirtualBox VMs</filename> + directory. + </para> + <para> + The actual file name may not correspond directly to the VM name + if it violates the host OS file name requirements (such as using + the path separator or other reserved characters, they will be + substituted with a placeholder). If you later rename the VM, the + file and folder names will be updated to match the new name + automatically. + </para> + </refsect1> + + <refsect1> + <title>Command Options</title> + <para> + In addition to specifying the name or UUID of the VM, which is + required, you can specify any of the following options: + </para> + <variablelist> + <varlistentry> + <term><option>--basefolder=<replaceable>basefolder</replaceable></option></term> + <listitem><para> + Specifies the name of the folder in which to save the + machine configuration file for the new VM. + </para><para> + Note that the names of the file and the folder do not change + if you rename the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--default</option></term> + <listitem><para> + Applies a default hardware configuration for the specified + guest OS. By default, the VM is created with minimal + hardware. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--group=<replaceable>group-ID</replaceable>,...</option></term> + <listitem><para> + Assigns the VM to the specified groups. If you specify more + than one group, separate each group name with a comma. + </para><para> + Note that each group is identified by a group ID that starts + with a slash character (<literal>/</literal>) so that groups + can be nested. By default, a VM is always assigned + membership to the <literal>/</literal> group. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ostype=<replaceable>ostype</replaceable></option></term> + <listitem><para> + Specifies the guest OS to run in the VM. Run the + <command>VBoxManage list ostypes</command> command to see + the available OS types. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--register</option></term> + <listitem><para> + Registers the VM with your &product-name; installation. By + default, the <command>VBoxManage createvm</command> command + creates only the XML configuration for the VM but does not + register the VM. If you do not register the VM at creation, + you can run the <command>VBoxManage registervm</command> + command after you create the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) of the + VM. Ensure that this UUID is unique within the + &product-name; namespace of the host or of its VM group + memberships if you decide to register the VM. By default, + &product-name; provides the UUID. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cipher <replaceable>cipher</replaceable></option></term> + <listitem><para> + Specifies the cipher to use for encryption. Valid values are + <literal>AES-128</literal> or + <literal>AES-256</literal>. + </para><para> + This option enables you to set up encryption on VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password-id <replaceable>password-id</replaceable></option></term> + <listitem><para> + Specifies a new password identifier that is used for correct + identification when supplying multiple passwords for the VM. + </para><para> + This option enables you to set up encryption on VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password <replaceable>file</replaceable></option></term> + <listitem><para> + Use the <option>--password</option> to supply the encryption + password of the VM. Either specify the absolute pathname of a + password file on the host operating system, or <literal>-</literal> + to prompt you for the password on the command line. + </para><para> + This option enables you to set up encryption on VM. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command creates a VM called <literal>vm2</literal> + where you plan to run a 64-bit version of Oracle Linux. + </para> +<screen>$ VBoxManage createvm --name "vm2" --ostype "Oracle_64"</screen> + <para> + The following command creates and registers a VM called + <literal>vm3</literal>. + </para> +<screen>$ VBoxManage createvm --name "vm3" --register</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-list" />, + <xref linkend="vboxmanage-registervm" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-debugvm.xml b/doc/manual/en_US/man_VBoxManage-debugvm.xml new file mode 100644 index 00000000..82a1c8f4 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-debugvm.xml @@ -0,0 +1,666 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage debugvm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-debugvm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage debugvm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-debugvm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-debugvm</refname> + <refpurpose>introspection and guest debugging</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-dumpvmcore"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">dumpvmcore</arg> + <arg>--filename=<replaceable>name</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-info"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">info</arg> + <arg choice="req"><replaceable>item</replaceable></arg> + <arg rep="repeat"><replaceable>args</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-injectnmi"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">injectnmi</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-log"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">log</arg> + <group><arg>--release</arg><arg>--debug</arg></group> + <arg rep="repeat"><replaceable>group-settings</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-logdest"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">logdest</arg> + <group><arg>--release</arg><arg>--debug</arg></group> + <arg rep="repeat"><replaceable>destinations</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-logflags"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">logflags</arg> + <group><arg>--release</arg><arg>--debug</arg></group> + <arg rep="repeat"><replaceable>flags</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-osdetect"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">osdetect</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-osinfo"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">osinfo</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-osdmesg"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">osdmesg</arg> + <arg>--lines=<replaceable>lines</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-getregisters"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">getregisters</arg> + <arg>--cpu=<replaceable>id</replaceable></arg> + <arg rep="repeat"><replaceable>reg-set.reg-name</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-setregisters"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">setregisters</arg> + <arg>--cpu=<replaceable>id</replaceable></arg> + <arg rep="repeat"><replaceable>reg-set.reg-name</replaceable>=<replaceable>value</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-show"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">show</arg> + <group><arg>--human-readable</arg><arg>--sh-export</arg><arg>--sh-eval</arg><arg>--cmd-set</arg></group> + <arg rep="repeat"><replaceable>settings-item</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-stack"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">stack</arg> + <arg>--cpu=<replaceable>id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-statistics"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">statistics</arg> + <arg>--reset</arg> + <arg>--descriptions</arg> + <arg>--pattern=<replaceable>pattern</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-guestsample"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">guestsample</arg> + <arg>--filename=<replaceable>filename</replaceable></arg> + <arg>--sample-interval-us=<replaceable>interval</replaceable></arg> + <arg>--sample-time-us=<replaceable>time</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + <refsect1> + <title>Description</title> + + <para>The "debugvm" commands are for experts who want to tinker with the + exact details of virtual machine execution. Like the VM debugger + described in <xref linkend="ts_debugger" />, these commands are only useful if you are + very familiar with the details of the PC architecture and how to debug + software.</para> + + <refsect2 id="vboxmanage-debugvm-common-options"> + <title>Common options</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>The subcommands of <command>debugvm</command> all operate on a running virtual + machine:</para> + <variablelist> + <varlistentry> + <term><replaceable>uuid|vmname</replaceable></term> + <listitem><para>Either the UUID or the name (case sensitive) of a VM.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-dumpvmcore"> + <title>debugvm dumpvmcore</title> + <remark role="help-copy-synopsis"/> + <para> + Creates a system dump file of the specified VM. This file will have + the standard ELF core format (with custom sections); see + <xref linkend="ts_guest-core-format" />. + </para> + <para> + This corresponds to the <command>writecore</command> command in the debugger. + </para> + <variablelist> + <varlistentry> + <term><option>--filename=<replaceable>filename</replaceable></option></term> + <listitem><para>The name of the output file.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-info"> + <title>debugvm info</title> + <remark role="help-copy-synopsis"/> + <para> + Displays info items relating to the VMM, device emulations and + associated drivers. + </para> + <para> + This corresponds to the <command>info</command> command in the debugger. + </para> + <variablelist> + <varlistentry> + <term><replaceable>item</replaceable></term> + <listitem> + <para>Name of the info item to display. The special name + <option>help</option> will list all the available info items and + hints about optional arguments.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><replaceable>args</replaceable></term> + <listitem> + <para>Optional argument string for the info item handler. Most info items + does not take any extra arguments. Arguments not recognized are generally + ignored.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-injectnmi"> + <title>debugvm injectnmi</title> + <remark role="help-copy-synopsis"/> + <para> + Causes a non-maskable interrupt (NMI) to be injected into the guest. This + might be useful for certain debugging scenarios. What happens exactly is + dependent on the guest operating system, but an NMI can crash the whole + guest operating system. Do not use unless you know what you're doing. + </para> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-log"> + <title>debugvm log</title> + <remark role="help-copy-synopsis"/> + <para> + Changes the group settings for either debug (<option>--debug</option>) + or release (<option>--release</option>) logger of the VM process. + </para> + <para> + The <replaceable>group-settings</replaceable> are typically strings on the form + <computeroutput>em.e.f.l</computeroutput>, <computeroutput>hm=~0</computeroutput> + and <computeroutput>-em.f</computeroutput>. Basic wildcards are supported for + group matching. The <computeroutput>all</computeroutput> group is an alias for + all the groups. + </para> + <para> + Please do keep in mind that the group settings are applied as modifications + to the current ones. + </para> + <para> + This corresponds to the <command>log</command> command in the debugger. + </para> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-logdest"> + <title>debugvm logdest</title> + <remark role="help-copy-synopsis"/> + <para> + Changes the destination settings for either debug (<option>--debug</option>) + or release (<option>--release</option>) logger of the VM process. For details + on the destination format, the best source is src/VBox/Runtime/common/log/log.cpp. + </para> + <para> + The <replaceable>destinations</replaceable> is one or more mnemonics, optionally + prefixed by "no" to disable them. Some of them take values after a ":" or "=" + separator. Multiple mnemonics can be separated by space or given as separate + arguments on the command line. + </para> + <para> + List of available destination: + </para> + <variablelist> + <varlistentry> + <term><option>file[=<replaceable>file</replaceable>], nofile</option></term> + <listitem><para>Specifies a log file. If no filename is given, one will be + generated based on the current UTC time and VM process name and placed in + the current directory of the VM process. Note that this will currently not + have any effect if the log file has already been opened. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>dir=<replaceable>directory</replaceable>, nodir</option></term> + <listitem><para>Specifies the output directory for log files. Note that this + will currently not have any effect if the log file has already been opened. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>history=<replaceable>count</replaceable>, nohistory</option></term> + <listitem><para>A non-zero value enables log historization, with the value + specifying how many old log files to keep. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>histsize=<replaceable>bytes</replaceable></option></term> + <listitem><para>The max size of a log file before it is historized. Default is infinite.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>histtime=<replaceable>seconds</replaceable></option></term> + <listitem><para>The max age (in seconds) of a log file before it is historized. Default is infinite.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>ringbuffer, noringbuffer</option></term> + <listitem><para>Only log to the log buffer until an explicit flush (e.g. via an assertion) + occurs. This is fast and saves diskspace.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>stdout, nostdout</option></term> + <listitem><para>Write the log content to standard output.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>stdout, nostdout</option></term> + <listitem><para>Write the log content to standard error.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>debugger, nodebugger</option></term> + <listitem><para>Write the log content to the debugger, if supported by the host OS.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>com, nocom</option></term> + <listitem><para>Writes logging to the COM port. This is only applicable for raw-mode and ring-0 logging.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>user, nouser</option></term> + <listitem><para>Custom destination which has no meaning to VM processes..</para></listitem> + </varlistentry> + </variablelist> + <para> + This corresponds to the <command>logdest</command> command in the debugger. + </para> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-logflags"> + <title>debugvm logflags</title> + <remark role="help-copy-synopsis"/> + <para> + Changes the flags on either debug (<option>--debug</option>) or release + (<option>--release</option>) logger of the VM process. Please note that the + modifications are applied onto the existing changes, they are not replacing them. + </para> + <para> + The <replaceable>flags</replaceable> are a list of flag mnemonics, optionally + prefixed by a "no", "!", "~" or "-" to negate their meaning. The "+" prefix + can be used to undo previous negation or use as a separator, though better use + whitespace or separate arguments for that. + </para> + <para> + List of log flag mnemonics, with their counter form where applicable + (asterisk indicates defaults): + </para> + <variablelist> + <varlistentry> + <term><option>enabled*, disabled</option></term> + <listitem><para>Enables or disables logging.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>buffered, unbuffered*</option></term> + <listitem><para>Enabling buffering of log output before it hits the destinations.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>writethrough(/writethru)</option></term> + <listitem><para>Whether to open the destination file with writethru buffering settings or not.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>flush</option></term> + <listitem><para>Enables flushing of the output file (to disk) after each log statement.</para></listitem> + </varlistentry> + <!-- Prefixes --> + <varlistentry> + <term><option>lockcnts</option></term> + <listitem><para>Prefix each log line with lock counts for the current thread.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>cpuid</option></term> + <listitem><para>Prefix each log line with the ID of the current CPU.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>pid</option></term> + <listitem><para>Prefix each log line with the current process ID.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>flagno</option></term> + <listitem><para>Prefix each log line with the numberic flags corresponding to the log statement.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>flag</option></term> + <listitem><para>Prefix each log line with the flag mnemonics corresponding to the log statement.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>groupno</option></term> + <listitem><para>Prefix each log line with the log group number for the log statement producing it.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>group</option></term> + <listitem><para>Prefix each log line with the log group name for the log statement producing it.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>tid</option></term> + <listitem><para>Prefix each log line with the current thread identifier.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>thread</option></term> + <listitem><para>Prefix each log line with the current thread name.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>time</option></term> + <listitem><para>Prefix each log line with the current UTC wall time.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>timeprog</option></term> + <listitem><para>Prefix each log line with the current monotonic time since the start of the program.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>msprog</option></term> + <listitem><para>Prefix each log line with the current monotonic timestamp value in milliseconds since the start of the program.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>ts</option></term> + <listitem><para>Prefix each log line with the current monotonic timestamp value in nanoseconds.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>tsc</option></term> + <listitem><para>Prefix each log line with the current CPU timestamp counter (TSC) value.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>rel, abs*</option></term> + <listitem><para>Selects the whether <computeroutput>ts</computeroutput> and + <computeroutput>tsc</computeroutput> prefixes should be displayed as relative to the + previous log line or as absolute time.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>hex*, dec</option></term> + <listitem><para>Selects the whether the <computeroutput>ts</computeroutput> and + <computeroutput>tsc</computeroutput> prefixes should be formatted as hexadecimal + or decimal.</para></listitem> + </varlistentry> + + <!-- Suffixes and weird stuff. --> + <varlistentry> + <term><option>custom</option></term> + <listitem><para>Custom log prefix, has by default no meaning for VM processes.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>usecrlf, uself*</option></term> + <listitem><para>Output with DOS style (CRLF) or just UNIX style (LF) line endings.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>overwrite*, append</option></term> + <listitem><para>Overwrite the destination file or append to it.</para></listitem> + </varlistentry> + </variablelist> + + <para> + This corresponds to the <command>logflags</command> command in the debugger. + </para> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-osdetect"> + <title>debugvm osdetect</title> + <remark role="help-copy-synopsis"/> + <para> + Make the VMM's debugger facility (re)-detect the guest operating system (OS). + This will first load all debugger plug-ins. + </para> + <para> + This corresponds to the <command>detect</command> command in the debugger. + </para> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-osinfo"> + <title>debugvm osinfo</title> + <remark role="help-copy-synopsis"/> + <para> + Displays information about the guest operating system (OS) previously + detected by the VMM's debugger facility. + </para> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-osdmesg"> + <title>debugvm osdmesg</title> + <remark role="help-copy-synopsis"/> + <para> + Displays the guest OS kernel log, if detected and supported. + </para> + <variablelist> + <varlistentry> + <term><option>--lines=<replaceable>lines</replaceable></option></term> + <listitem><para>Number of lines of the log to display, counting from + the end. The default is infinite.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-getregisters"> + <title>debugvm getregisters</title> + <remark role="help-copy-synopsis"/> + <para> + Retrieves register values for guest CPUs and emulated devices. + </para> + <variablelist> + <varlistentry> + <term><replaceable>reg-set.reg-name</replaceable></term> + <listitem> + <para>One of more registers, each having one of the following forms:</para> + <orderedlist> + <listitem><para>register-set.register-name.sub-field</para></listitem> + <listitem><para>register-set.register-name</para></listitem> + <listitem><para>cpu-register-name.sub-field</para></listitem> + <listitem><para>cpu-register-name</para></listitem> + <listitem><para>all</para></listitem> + </orderedlist> + <para>The <replaceable>all</replaceable> form will cause all registers + to be shown (no sub-fields). The registers names are case-insensitive. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--cpu=<replaceable>id</replaceable></option></term> + <listitem><para>Selects the CPU register set when specifying just a + CPU register (3rd and 4th form). The default is 0.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-setregisters"> + <title>debugvm setregisters</title> + <remark role="help-copy-synopsis"/> + <para> + Changes register values for guest CPUs and emulated devices. + </para> + <variablelist> + <varlistentry> + <term><replaceable>reg-set.reg-name=value</replaceable></term> + <listitem> + <para>One of more register assignment, each having one of the following forms:</para> + <orderedlist> + <listitem><para>register-set.register-name.sub-field=value</para></listitem> + <listitem><para>register-set.register-name=value</para></listitem> + <listitem><para>cpu-register-name.sub-field=value</para></listitem> + <listitem><para>cpu-register-name=value</para></listitem> + </orderedlist> + <para>The value format should be in the same style as what + <command>getregisters</command> displays, with the exception that + both octal and decimal can be used instead of hexadecimal.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--cpu=<replaceable>id</replaceable></option></term> + <listitem><para>Selects the CPU register set when specifying just a + CPU register (3rd and 4th form). The default is 0.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-show"> + <title>debugvm show</title> + <remark role="help-copy-synopsis"/> + <para> + Shows logging settings for the VM. + </para> + <variablelist> + <varlistentry> + <term><option>--human-readable</option></term> + <listitem><para>Selects human readable output.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--sh-export</option></term> + <listitem><para>Selects output format as bourne shell style <command>export</command> commands.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--sh-eval</option></term> + <listitem><para>Selects output format as bourne shell style <command>eval</command> command input.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cmd-set</option></term> + <listitem><para>Selects output format as DOS style <command>SET</command> commands.</para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>settings-item</replaceable></term> + <listitem> + <para>What to display. One or more of the following:</para> + <itemizedlist> + <listitem><para>logdbg-settings - debug log settings.</para></listitem> + <listitem><para>logrel-settings - release log settings.</para></listitem> + <listitem><para>log-settings - alias for both debug and release log settings.</para></listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="vboxmanage-debugvm-stack"> + <title>debugvm stack</title> + <remark role="help-copy-synopsis"/> + <para> + Unwinds the guest CPU stacks to the best of our ability. It is + recommended to first run the <command>osdetect</command> command, as this + gives both symbols and perhaps unwind information. + </para> + <variablelist> + <varlistentry> + <term><option>--cpu=<replaceable>id</replaceable></option></term> + <listitem><para>Selects a single guest CPU to display the stack for. The default is all CPUs.</para> </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="vboxmanage-debugvm-statistics"> + <title>debugvm statistics</title> + <remark role="help-copy-synopsis"/> + <para> + Displays or resets VMM statistics. + </para> + <para> + Retrieves register values for guest CPUs and emulated devices. + </para> + <variablelist> + <varlistentry> + <term><option>--pattern=<replaceable>pattern</replaceable></option></term> + <listitem><para>DOS/NT-style wildcards patterns for selecting statistics. Multiple + patterns can be specified by using the '|' (pipe) character as separator.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--reset</option></term> + <listitem><para>Select reset instead of display mode.</para></listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="vboxmanage-debugvm-guestsample"> + <title>debugvm guestsample</title> + <remark role="help-copy-synopsis"/> + <para> + Creates a sample report of the guest activity. + </para> + <para> + Retrieves the filename to dump the report to. + </para> + <variablelist> + <varlistentry> + <term><option>--filename=<replaceable>filename</replaceable></option></term> + <listitem><para>The filename to dump the sample report to.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--sample-interval-us=<replaceable>interval</replaceable></option></term> + <listitem><para>The interval in microseconds between guest samples.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--sample-time-us=<replaceable>time</replaceable></option></term> + <listitem><para>The amount of microseconds to take guest samples.</para> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + </refsect1> + +</refentry> + diff --git a/doc/manual/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xml b/doc/manual/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xml new file mode 100644 index 00000000..d368c964 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xml @@ -0,0 +1,231 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Manually generated from src/VBox/Main/idl/VirtualBox.xidl by 'kmk dhcpoptions'. + DO NOT EDIT! +--> +<!-- + Copyright (C) 2019-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + + <variablelist> + <varlistentry> + <term>1 - SubnetMask</term> + <listitem><para>IPv4 netmask. Set to the value of the --netmask option by default.</para></listitem> + </varlistentry> <varlistentry> + <term>2 - TimeOffset</term> + <listitem><para>UTC offset in seconds (32-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>3 - Routers</term> + <listitem><para>Space separated list of IPv4 router addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>4 - TimeServers</term> + <listitem><para>Space separated list of IPv4 time server (RFC 868) addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>5 - NameServers</term> + <listitem><para>Space separated list of IPv4 name server (IEN 116) addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>6 - DomainNameServers</term> + <listitem><para>Space separated list of IPv4 DNS addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>7 - LogServers</term> + <listitem><para>Space separated list of IPv4 log server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>8 - CookieServers</term> + <listitem><para>Space separated list of IPv4 cookie server (RFC 865) addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>9 - LPRServers</term> + <listitem><para>Space separated list of IPv4 line printer server (RFC 1179) addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>10 - ImpressServers</term> + <listitem><para>Space separated list of IPv4 imagen impress server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>11 - ResourseLocationServers</term> + <listitem><para>Space separated list of IPv4 resource location (RFC 887) addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>12 - HostName</term> + <listitem><para>The client name. See RFC 1035 for character limits. </para></listitem> + </varlistentry> <varlistentry> + <term>13 - BootFileSize</term> + <listitem><para>Number of 512 byte blocks making up the boot file (16-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>14 - MeritDumpFile</term> + <listitem><para>Client core file.</para></listitem> + </varlistentry> <varlistentry> + <term>15 - DomainName</term> + <listitem><para>Domain name for the client.</para></listitem> + </varlistentry> <varlistentry> + <term>16 - SwapServer</term> + <listitem><para>IPv4 address of the swap server that the client should use.</para></listitem> + </varlistentry> <varlistentry> + <term>17 - RootPath</term> + <listitem><para>The path to the root disk the client should use.</para></listitem> + </varlistentry> <varlistentry> + <term>18 - ExtensionPath</term> + <listitem><para>Path to a file containing additional DHCP options (RFC2123).</para></listitem> + </varlistentry> <varlistentry> + <term>19 - IPForwarding</term> + <listitem><para>Whether IP forwarding should be enabled by the client (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>20 - OptNonLocalSourceRouting</term> + <listitem><para>Whether non-local datagrams should be forwarded by the client (boolean)</para></listitem> + </varlistentry> <varlistentry> + <term>21 - PolicyFilter</term> + <listitem><para>List of IPv4 addresses and masks paris controlling non-local source routing.</para></listitem> + </varlistentry> <varlistentry> + <term>22 - MaxDgramReassemblySize</term> + <listitem><para>The maximum datagram size the client should reassemble (16-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>23 - DefaultIPTTL</term> + <listitem><para>The default time-to-leave on outgoing (IP) datagrams (8-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>24 - PathMTUAgingTimeout</term> + <listitem><para>RFC1191 path MTU discovery timeout value in seconds (32-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>25 - PathMTUPlateauTable</term> + <listitem><para>RFC1191 path MTU discovery size table, sorted in ascending order (list of 16-bit decimal values).</para></listitem> + </varlistentry> <varlistentry> + <term>26 - InterfaceMTU</term> + <listitem><para>The MTU size for the interface (16-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>27 - AllSubnetsAreLocal</term> + <listitem><para>Indicates whether the MTU size is the same for all subnets (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>28 - BroadcastAddress</term> + <listitem><para>Broadcast address (RFC1122) for the client to use (IPv4 address).</para></listitem> + </varlistentry> <varlistentry> + <term>29 - PerformMaskDiscovery</term> + <listitem><para>Whether to perform subnet mask discovery via ICMP (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>30 - MaskSupplier</term> + <listitem><para>Whether to respond to subnet mask requests via ICMP (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>31 - PerformRouterDiscovery</term> + <listitem><para>Whether to perform router discovery (RFC1256) (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>32 - RouterSolicitationAddress</term> + <listitem><para>Where to send router solicitation requests (RFC1256) (IPv4 address).</para></listitem> + </varlistentry> <varlistentry> + <term>33 - StaticRoute</term> + <listitem><para>List of network and router address pairs addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>34 - TrailerEncapsulation</term> + <listitem><para>Whether to negotiate the use of trailers for ARP (RTF893) (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>35 - ARPCacheTimeout</term> + <listitem><para>The timeout in seconds for ARP cache entries (32-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>36 - EthernetEncapsulation</term> + <listitem><para>Whether to use IEEE 802.3 (RTF1042) rather than of v2 (RFC894) ethernet encapsulation (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>37 - TCPDefaultTTL</term> + <listitem><para>Default time-to-live for TCP sends (non-zero 8-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>38 - TCPKeepaliveInterval</term> + <listitem><para>The interface in seconds between TCP keepalive messages (32-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>39 - TCPKeepaliveGarbage</term> + <listitem><para>Whether to include a byte of garbage in TCP keepalive messages for backward compatibility (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>40 - NISDomain</term> + <listitem><para>The NIS (Sun Network Information Services) domain name (string).</para></listitem> + </varlistentry> <varlistentry> + <term>41 - NISServers</term> + <listitem><para>Space separated list of IPv4 NIS server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>42 - NTPServers</term> + <listitem><para>Space separated list of IPv4 NTP (RFC1035) server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>43 - VendorSpecificInfo</term> + <listitem><para>Vendor specific information. Only accessible using --set-opt-hex.</para></listitem> + </varlistentry> <varlistentry> + <term>44 - NetBIOSNameServers</term> + <listitem><para>Space separated list of IPv4 NetBIOS name server (NBNS) addresses (RFC1001,RFC1002).</para></listitem> + </varlistentry> <varlistentry> + <term>45 - NetBIOSDatagramServers</term> + <listitem><para>Space separated list of IPv4 NetBIOS datagram distribution server (NBDD) addresses (RFC1001,RFC1002).</para></listitem> + </varlistentry> <varlistentry> + <term>46 - NetBIOSNodeType</term> + <listitem><para>NetBIOS node type (RFC1001,RFC1002): 1=B-node, 2=P-node, 4=M-node, and 8=H-node (8-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>47 - NetBIOSScope</term> + <listitem><para>NetBIOS scope (RFC1001,RFC1002). Only accessible using --set-opt-hex.</para></listitem> + </varlistentry> <varlistentry> + <term>48 - XWindowsFontServers</term> + <listitem><para>Space separated list of IPv4 X windows font server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>49 - XWindowsDisplayManager</term> + <listitem><para>Space separated list of IPv4 X windows display manager addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>62 - NetWareIPDomainName</term> + <listitem><para>Netware IP domain name (RFC2242) (string).</para></listitem> + </varlistentry> <varlistentry> + <term>63 - NetWareIPInformation</term> + <listitem><para>Netware IP information (RFC2242). Only accessible using --set-opt-hex.</para></listitem> + </varlistentry> <varlistentry> + <term>64 - NISPlusDomain</term> + <listitem><para>The NIS+ domain name (string).</para></listitem> + </varlistentry> <varlistentry> + <term>65 - NISPlusServers</term> + <listitem><para>Space separated list of IPv4 NIS+ server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>66 - TFTPServerName</term> + <listitem><para>TFTP server name (string).</para></listitem> + </varlistentry> <varlistentry> + <term>67 - BootfileName</term> + <listitem><para>Bootfile name (string).</para></listitem> + </varlistentry> <varlistentry> + <term>68 - MobileIPHomeAgents</term> + <listitem><para>Space separated list of IPv4 mobile IP agent addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>69 - SMTPServers</term> + <listitem><para>Space separated list of IPv4 simple mail transport protocol (SMPT) server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>70 - POP3Servers</term> + <listitem><para>Space separated list of IPv4 post office protocol 3 (POP3) server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>71 - NNTPServers</term> + <listitem><para>Space separated list of IPv4 network news transport protocol (NTTP) server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>72 - WWWServers</term> + <listitem><para>Space separated list of default IPv4 world wide web (WWW) server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>73 - FingerServers</term> + <listitem><para>Space separated list of default IPv4 finger server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>74 - IRCServers</term> + <listitem><para>Space separated list of default IPv4 internet relay chat (IRC) server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>75 - StreetTalkServers</term> + <listitem><para>Space separated list of IPv4 StreetTalk server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>76 - STDAServers</term> + <listitem><para>Space separated list of IPv4 StreetTalk directory assistance (STDA) server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>78 - SLPDirectoryAgent</term> + <listitem><para>Addresses of one or more service location protocol (SLP) directory agent, and an indicator of whether their use is mandatory. Only accessible using --set-opt-hex.</para></listitem> + </varlistentry> <varlistentry> + <term>79 - SLPServiceScope</term> + <listitem><para>List of service scopes for the service location protocol (SLP) and whether using the list is mandator. Only accessible using --set-opt-hex.</para></listitem> + </varlistentry> <varlistentry> + <term>119 - DomainSearch</term> + <listitem><para>Domain search list, see RFC3397 and section 4.1.4 in RFC1035 for encoding. Only accessible using --set-opt-hex.</para></listitem> + </varlistentry> + </variablelist> diff --git a/doc/manual/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xsl b/doc/manual/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xsl new file mode 100644 index 00000000..27897fa5 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xsl @@ -0,0 +1,132 @@ +<?xml version="1.0"?> +<!-- + Stylesheet that extracts the DHCP option descriptions from + VirtualBox.xidl for cut & paste into man_VBoxManage-dhcpserver.xml. +--> +<!-- + Copyright (C) 2019-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<xsl:stylesheet + version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + > + + <xsl:output method="text" version="1.0" encoding="utf-8" indent="yes"/> + <xsl:strip-space elements="*"/> + + +<!-- Default operation is to supress output --> +<xsl:template match="node()|@*"> + <xsl:apply-templates/> +</xsl:template> + +<!-- +The work. +--> +<xsl:template mode="emit" match="link[@to='IDHCPServer::networkMask']"> + <xsl:text>the value of the --netmask option</xsl:text> +</xsl:template> + +<xsl:template mode="emit" match="link[@to='DHCPOptionEncoding::Hex']"> + <xsl:text>--set-opt-hex</xsl:text> +</xsl:template> + +<xsl:template match="desc" mode="emit"> + <xsl:apply-templates mode="emit"/> +</xsl:template> + +<xsl:template match="/idl/library/application/enum[@name='DHCPOption']/const"> + <!-- <xsl:message><xsl:text>debug: </xsl:text><xsl:call-template name="get-node-path"/></xsl:message> --> + <xsl:text> <varlistentry> + <term></xsl:text><xsl:value-of select="concat(@value,' - ',@name)"/><xsl:text></term> + <listitem><para></xsl:text> + <xsl:apply-templates mode="emit"/> + <xsl:text></para></listitem> + </varlistentry></xsl:text> +</xsl:template> + +<xsl:template match="/"> + <xsl:text><?xml version="1.0" encoding="UTF-8"?> +<!-- + Manually generated from src/VBox/Main/idl/VirtualBox.xidl by 'kmk dhcpoptions'. + DO NOT EDIT! +--> +<!-- +Copyright (C) 2019-2023 Oracle Corporation and/or its affiliates. + +This file is part of VirtualBox Open Source Edition (OSE), as +available from https://www.virtualbox.org. + +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, in version 3 of the +License. + +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, see <https://www.gnu.org/licenses>. +--> + + <variablelist> +</xsl:text> + <xsl:apply-templates/> + <xsl:text> + </variablelist> +</xsl:text> +</xsl:template> + + +<!-- + Debug/Diagnostics: Return the path to the specified node (by default the current). + --> +<xsl:template name="get-node-path"> + <xsl:param name="Node" select="."/> + <xsl:for-each select="$Node"> + <xsl:for-each select="ancestor-or-self::node()"> + <xsl:choose> + <xsl:when test="name(.) = ''"> + <xsl:text>text()</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="concat('/', name(.))"/> + <xsl:choose> + <xsl:when test="@id"> + <xsl:text>[@id=</xsl:text> + <xsl:value-of select="@id"/> + <xsl:text>]</xsl:text> + </xsl:when> + <xsl:when test="position() > 1"> + <xsl:text>[</xsl:text><xsl:value-of select="position()"/><xsl:text>]</xsl:text> + </xsl:when> + </xsl:choose> + </xsl:otherwise> + </xsl:choose> + </xsl:for-each> + </xsl:for-each> +</xsl:template> + +</xsl:stylesheet> + diff --git a/doc/manual/en_US/man_VBoxManage-dhcpserver.xml b/doc/manual/en_US/man_VBoxManage-dhcpserver.xml new file mode 100644 index 00000000..9300d88c --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-dhcpserver.xml @@ -0,0 +1,608 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage dhcpserver +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-dhcpserver" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage dhcpserver</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-dhcpserver</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-dhcpserver</refname> + <refpurpose>DHCP server management</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-add"> + <command>VBoxManage dhcpserver add</command> + <group choice="req"> + <arg choice="plain">--network=<replaceable>netname</replaceable></arg> + <arg choice="plain">--interface=<replaceable>ifname</replaceable></arg> + </group> + <arg choice="req">--server-ip=<replaceable>address</replaceable></arg> + <arg choice="req">--netmask=<replaceable>mask</replaceable></arg> + <arg choice="req">--lower-ip=<replaceable>address</replaceable></arg> + <arg choice="req">--upper-ip=<replaceable>address</replaceable></arg> + <group choice="req"> + <arg choice="plain">--enable</arg> + <arg choice="plain">--disable</arg> + </group> + <sbr/> + <group rep="repeat"> + <arg>--global</arg> + <arg rep="repeat">--set-opt=<replaceable>dhcp-opt-no value</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>dhcp-opt-no hexstring</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg>--min-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--default-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--max-lease-time=<replaceable>seconds</replaceable></arg> + </group> + <sbr/> + <group rep="repeat"> + <arg choice="req">--group=<replaceable>name</replaceable></arg> + <arg rep="repeat">--set-opt=<replaceable>dhcp-opt-no value</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>dhcp-opt-no hexstring</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--incl-mac=<replaceable>address</replaceable></arg> + <arg rep="repeat">--excl-mac=<replaceable>address</replaceable></arg> + <arg rep="repeat">--incl-mac-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--excl-mac-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--incl-vendor=<replaceable>string</replaceable></arg> + <arg rep="repeat">--excl-vendor=<replaceable>string</replaceable></arg> + <arg rep="repeat">--incl-vendor-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--excl-vendor-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--incl-user=<replaceable>string</replaceable></arg> + <arg rep="repeat">--excl-user=<replaceable>string</replaceable></arg> + <arg rep="repeat">--incl-user-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--excl-user-wild=<replaceable>pattern</replaceable></arg> + <arg>--min-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--default-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--max-lease-time=<replaceable>seconds</replaceable></arg> + </group> + <sbr/> + <group rep="repeat"> + <arg choice="req">--vm=<replaceable>name|uuid</replaceable></arg> + <arg>--nic=<replaceable>1-N</replaceable></arg> + <arg rep="repeat">--set-opt=<replaceable>dhcp-opt-no value</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>dhcp-opt-no hexstring</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg>--min-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--default-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--max-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--fixed-address=<replaceable>address</replaceable></arg> + </group> + <sbr/> + <group rep="repeat"> + <arg choice="req">--mac-address=<replaceable>address</replaceable></arg> + <arg rep="repeat">--set-opt=<replaceable>dhcp-opt-no value</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>dhcp-opt-no hexstring</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg>--min-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--default-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--max-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--fixed-address=<replaceable>address</replaceable></arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-modify"> + <command>VBoxManage dhcpserver modify</command> + <group choice="req"> + <arg choice="plain">--network=<replaceable>netname</replaceable></arg> + <arg choice="plain">--interface=<replaceable>ifname</replaceable></arg> + </group> + <arg>--server-ip=<replaceable>address</replaceable></arg> + <arg>--lower-ip=<replaceable>address</replaceable></arg> + <arg>--upper-ip=<replaceable>address</replaceable></arg> + <arg>--netmask=<replaceable>mask</replaceable></arg> + <group> + <arg choice="plain">--enable</arg> + <arg choice="plain">--disable</arg> + </group> + <sbr/> + <group rep="repeat"> + <arg>--global</arg> + <arg rep="repeat">--del-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--set-opt=<replaceable>dhcp-opt-no value</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>dhcp-opt-no hexstring</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--unforce-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--unsupress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg>--min-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--default-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--max-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--remove-config</arg> + </group> + <sbr/> + <group rep="repeat"> + <arg choice="req">--group=<replaceable>name</replaceable></arg> + <arg rep="repeat">--set-opt=<replaceable>dhcp-opt-no value</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>dhcp-opt-no hexstring</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--unforce-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--unsupress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--del-mac=<replaceable>address</replaceable></arg> + <arg rep="repeat">--incl-mac=<replaceable>address</replaceable></arg> + <arg rep="repeat">--excl-mac=<replaceable>address</replaceable></arg> + <arg rep="repeat">--del-mac-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--incl-mac-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--excl-mac-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--del-vendor=<replaceable>string</replaceable></arg> + <arg rep="repeat">--incl-vendor=<replaceable>string</replaceable></arg> + <arg rep="repeat">--excl-vendor=<replaceable>string</replaceable></arg> + <arg rep="repeat">--del-vendor-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--incl-vendor-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--excl-vendor-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--del-user=<replaceable>string</replaceable></arg> + <arg rep="repeat">--incl-user=<replaceable>string</replaceable></arg> + <arg rep="repeat">--excl-user=<replaceable>string</replaceable></arg> + <arg rep="repeat">--del-user-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--incl-user-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--excl-user-wild=<replaceable>pattern</replaceable></arg> + <arg>--zap-conditions</arg> + <arg>--min-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--default-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--max-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--remove-config</arg> + </group> + <sbr/> + <group rep="repeat"> + <arg choice="req">--vm=<replaceable>name|uuid</replaceable></arg> + <arg>--nic=<replaceable>1-N</replaceable></arg> + <arg rep="repeat">--del-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--set-opt=<replaceable>dhcp-opt-no value</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>dhcp-opt-no hexstring</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--unforce-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--unsupress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg>--min-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--default-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--max-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--fixed-address=<replaceable>address</replaceable></arg> + <arg>--remove-config</arg> + </group> + <sbr/> + <group rep="repeat"> + <arg choice="req">--mac-address=<replaceable>address</replaceable></arg> + <arg rep="repeat">--del-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--set-opt=<replaceable>dhcp-opt-no value</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>dhcp-opt-no hexstring</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--unforce-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--unsupress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg>--min-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--default-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--max-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--fixed-address=<replaceable>address</replaceable></arg> + <arg>--remove-config</arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-remove"> + <command>VBoxManage dhcpserver remove</command> + <group choice="req"> + <arg choice="plain">--network=<replaceable>netname</replaceable></arg> + <arg choice="plain">--interface=<replaceable>ifname</replaceable></arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-start"> + <command>VBoxManage dhcpserver start</command> + <group choice="req"> + <arg choice="plain">--network=<replaceable>netname</replaceable></arg> + <arg choice="plain">--interface=<replaceable>ifname</replaceable></arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-restart"> + <command>VBoxManage dhcpserver restart</command> + <group choice="req"> + <arg choice="plain">--network=<replaceable>netname</replaceable></arg> + <arg choice="plain">--interface=<replaceable>ifname</replaceable></arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-stop"> + <command>VBoxManage dhcpserver stop</command> + <group choice="req"> + <arg choice="plain">--network=<replaceable>netname</replaceable></arg> + <arg choice="plain">--interface=<replaceable>ifname</replaceable></arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-findlease"> + <command>VBoxManage dhcpserver findlease</command> + <group choice="req"> + <arg choice="plain">--network=<replaceable>netname</replaceable></arg> + <arg choice="plain">--interface=<replaceable>ifname</replaceable></arg> + </group> + <arg choice="req">--mac-address=<replaceable>mac</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + The <command>dhcpserver</command> commands enable you to control the DHCP + server that is built into VirtualBox. You may find this useful when + using internal or host-only networking. Theoretically, you can also + enable it for a bridged network, but that may cause conflicts with other + DHCP servers in your physical network. + </para> + + <refsect2 id="vboxmanage-dhcpserver-common-options"> + <title>Common options</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>The subcommands of <command>dhcpserver</command> all operate on an + internal network that can be identified via its name or in the host-only + case via the host-only interface name:</para> + <variablelist> + <varlistentry> + <term>--network=<replaceable>netname</replaceable></term> + <listitem><para>The internal network name. This is the same as you + would use as value to the <command>VBoxManage modifyvm --intnet</command> + option when configuring a VM for internal networking. Or you see as + VBoxNetworkName in the output from + <command>VBoxManage list intnets</command>, + <command>VBoxManage list natnets</command>, or + <command>VBoxManage list hostonlyifs</command>. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--interface=<replaceable>ifname</replaceable></term> + <listitem><para>The host only interface name. This would be same value + as you would use for the <command>VBoxManage modifyvm --host-only-adapter</command> + option when configuring a VM to use a host-only network. The value + can also be found in the Name row in <command>VBoxManage list hostonlyifs</command>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-add"> + <title>dhcpserver add</title> + <remark role="help-copy-synopsis"/> + <para> + Adds a new DHCP server to a network or host-only interface. + </para> + <para> + Options configuring the DHCP server core: + </para> + <variablelist> + <varlistentry> + <term><option>--server-ip=<replaceable>address</replaceable></option></term> + <listitem><para>The IP address the DHCP server should use.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--lower-ip=<replaceable>address</replaceable></option>, <option>--upper-ip=<replaceable>address</replaceable></option></term> + <listitem><para>The IP address range for the DHCP server to manage. This + should not include the address of the DHCP server itself, but it must be + in the same network as it. The boundraries are inclusive, so both the + lower and upper addresses will be handed out to clients.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--netmask=<replaceable>mask</replaceable></option></term> + <listitem><para>The network mask. Typically 255.255.255.0.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--enable</option>, --disable</term> + <listitem><para>Whether to enable the DHCP server or disable it. If not specified, + the server will be created in disabled state and no IP addresses handed out.</para></listitem> + </varlistentry> + </variablelist> + <para> + Options selecting the scope: + </para> + <variablelist> + <varlistentry> + <term><option>--global</option></term> + <listitem><para>Set the configuration scope to global. Any subsequent + <option>--set-opt</option> options will be apply to all the DHCP clients.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vm=<replaceable>vmname|uuid</replaceable></option></term> + <listitem><para>Set the configuration scope to the first NIC of the specified VM. Any + subsequent <option>--set-opt</option> options will apply just to that interface, + nothing else.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic=<replaceable>1-N</replaceable></option></term> + <listitem><para>Set the configuration scope to a NIC other than first of + the VM specified the in <option>--vm</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mac-address=<replaceable>address</replaceable></option></term> + <listitem><para>Set the configuration scope to the specified MAC address.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--group=<replaceable>name</replaceable></option></term> + <listitem><para>Set the configuration scope to the specified group.</para></listitem> + </varlistentry> + </variablelist> + <para> + Options configuring the currently selected scope: + </para> + <variablelist> + <varlistentry> + <term><option>--set-opt=<replaceable>dhcp-opt-no value</replaceable></option></term> + <listitem><para>Adds the specified DHCP option number (0-255) and value. The + value format is option specific (typically human readable) and will be + validated by the API and the DHCP server. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--set-opt-hex=<replaceable>dhcp-opt-no hexstring</replaceable></option></term> + <listitem><para>Adds the specified DHCP option number (0-255) and value. The option value + is specified as a raw series of hex bytes, optionally separated by colons. No validation + is performed on these by the API or the DHCP server, they will be pass as specified to the + client. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--force-opt=<replaceable>dhcp-opt-no</replaceable></option></term> + <listitem><para>Forces the specified DHCP option number (0-255) onto to be + sent to the client whether it requested it or not (provided the option is + configured with a value at some level). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--suppress-opt=<replaceable>dhcp-opt-no</replaceable></option></term> + <listitem><para>Prevents the specified DHCP option number (0-255) from being + sent to the client when present in this or a high configuration scope. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--min-lease-time=<replaceable>seconds</replaceable></option></term> + <listitem><para>Sets the minimum lease time for the current scope in seconds. + Zero means taking the value from a higher option level or use default. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--default-lease-time=<replaceable>seconds</replaceable></option></term> + <listitem><para>Sets the default lease time for the current scope in seconds. + Zero means taking the value from a higher option level or use default. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--max-lease-time=<replaceable>seconds</replaceable></option></term> + <listitem><para>Sets the maximum lease time for the current scope in seconds. + Zero means taking the value from a higher option level or use default. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--fixed-address=<replaceable>address</replaceable></option></term> + <listitem><para>Fixed address assignment for a <option>--vm</option> or + <option>--mac-address</option> configuration scope. Any empty + <replaceable>address</replaceable> turns it back to dynamic address assignment. + </para></listitem> + </varlistentry> + </variablelist> + + <para> + Options configuring group membership conditions (excludes overrides includes): + </para> + <variablelist> + <varlistentry> + <term><option>--incl-mac=<replaceable>address</replaceable></option></term> + <listitem><para>Include the specific MAC address in the group.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--excl-mac=<replaceable>address</replaceable></option></term> + <listitem><para>Exclude the specific MAC address from the group.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--incl-mac-wild=<replaceable>pattern</replaceable></option></term> + <listitem><para>Include the specific MAC address pattern in the group.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--excl-mac-wild=<replaceable>pattern</replaceable></option></term> + <listitem><para>Exclude the specific MAC address pattern from the group.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--incl-vendor=<replaceable>string</replaceable></option></term> + <listitem><para>Include the specific vendor class ID in the group.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--excl-vendor=<replaceable>string</replaceable></option></term> + <listitem><para>Exclude the specific vendor class ID from the group.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--incl-vendor-wild=<replaceable>pattern</replaceable></option></term> + <listitem><para>Include the specific vendor class ID pattern in the group.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--excl-vendor-wild=<replaceable>pattern</replaceable></option></term> + <listitem><para>Exclude the specific vendor class ID pattern from the group.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--incl-user=<replaceable>string</replaceable></option></term> + <listitem><para>Include the specific user class ID in the group.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--excl-user=<replaceable>string</replaceable></option></term> + <listitem><para>Exclude the specific user class ID from the group.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--incl-user-wild=<replaceable>pattern</replaceable></option></term> + <listitem><para>Include the specific user class ID pattern in the group.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--excl-user-wild=<replaceable>pattern</replaceable></option></term> + <listitem><para>Exclude the specific user class ID pattern from the group.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-modify"> + <title>dhcpserver modify</title> + <remark role="help-copy-synopsis"/> + <para> + This modifies an existing DHCP server configuration. It takes the same + options as the <command>add</command> command with the addition of the following + on scope configuration: + </para> + <variablelist> + <varlistentry> + <term><option>--del-opt=<replaceable>dhcp-opt-no</replaceable></option></term> + <listitem><para>Counterpart to <option>--set-opt</option> that will cause the specified + DHCP option number (0-255) to be deleted from the server settings. Like with + <option>--set-opt</option> the scope of the deletion is governed by the + <option>--global</option>, <option>--vm</option>, <option>--mac-address</option> + and <option>--group</option> options. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unforce-opt=<replaceable>dhcp-opt-no</replaceable></option></term> + <listitem><para>Removes the specified DHCP option number (0-255) from the forced + option list (i.e. the reverse of <option>--force-opt</option>). Like with + <option>--set-opt</option> the scope of the deletion is governed by the + <option>--global</option>, <option>--vm</option>, <option>--mac-address</option> + and <option>--group</option> options. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unsuppress-opt=<replaceable>dhcp-opt-no</replaceable></option></term> + <listitem><para>Removes the specified DHCP option number (0-255) from the supressed + option list (i.e. the reverse of <option>--suppress-opt</option>). Like with + <option>--set-opt</option> the scope of the deletion is governed by the + <option>--global</option>, <option>--vm</option>, <option>--mac-address</option> + and <option>--group</option> options. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--remove-config</option></term> + <listitem><para>Removes the configuration currently being scoped. The + <option>--global</option> scope is not removable. The configuration scope will + change to <option>--global</option> after this option. + </para></listitem> + </varlistentry> + </variablelist> + <para> + And the addition of these group membership condition options: + </para> + <variablelist> + <varlistentry> + <term><option>--del-mac=<replaceable>address</replaceable></option></term> + <listitem><para>Delete the specific MAC address from the group conditions.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--del-mac-wild=<replaceable>pattern</replaceable></option></term> + <listitem><para>Delete the specific MAC address pattern from the group conditions.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--del-vendor=<replaceable>string</replaceable></option></term> + <listitem><para>Delete the specific vendor class ID from the group conditions.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--del-vendor-wild=<replaceable>pattern</replaceable></option></term> + <listitem><para>Delete the specific vendor class ID pattern from the group conditions.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--del-user=<replaceable>string</replaceable></option></term> + <listitem><para>Delete the specific user class ID from the group conditions.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--del-user-wild=<replaceable>pattern</replaceable></option></term> + <listitem><para>Delete the specific user class ID pattern from the group conditions.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--zap-conditions</option></term> + <listitem><para>Deletes all the group conditions.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-remove"> + <title>dhcpserver remove</title> + <remark role="help-copy-synopsis"/> + <para> + Removes the specified DHCP server. + </para> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-start"> + <title>dhcpserver start</title> + <remark role="help-copy-synopsis"/> + <para> + Start the specified DHCP server. + </para> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-restart"> + <title>dhcpserver restart</title> + <remark role="help-copy-synopsis"/> + <para> + Restarts the specified DHCP server. The DHCP server must be running. + </para> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-stop"> + <title>dhcpserver stop</title> + <remark role="help-copy-synopsis"/> + <para> + Stops the specified DHCP server. + </para> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-findlease"> + <title>dhcpserver findlease</title> + <remark role="help-copy-synopsis"/> + <para> + Performs a lease database lookup. This is mainly for getting the IP + address of a running VM. + </para> + <variablelist> + <varlistentry> + <term><option>--mac-address=<replaceable>mac</replaceable></option></term> + <listitem><para>The MAC address to lookup in the lease database.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-dhcpoptions"> + <title>Common DHCP Options:</title> + <remark role="help-scope" condition="DHCPSERVER_ADD|DHCPSERVER_MODIFY"/> + <!-- The following file is generated from src/VBox/Main/idl/VirtualBox.xidl: --> + <xi:include href="man_VBoxManage-dhcpserver-dhcpoptions.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> + </refsect2> + + </refsect1> + +</refentry> + diff --git a/doc/manual/en_US/man_VBoxManage-discardstate.xml b/doc/manual/en_US/man_VBoxManage-discardstate.xml new file mode 100644 index 00000000..52343eb6 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-discardstate.xml @@ -0,0 +1,102 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage discardstate +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-discardstate" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage discardstate</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-discardstate</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-discardstate</refname> + <refpurpose>discard the saved state of a virtual machine</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-discardstate"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage discardstate</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage discardstate</command> command discards + the saved state of a virtual machine (VM) that is not currently + running. This command causes the VM's operating system to restart + the next time you start the VM. + </para> + <note> + <para> + Where possible, avoid performing this action. The effects of + this command are equivalent to unplugging the power cable on a + physical machine. + </para> + </note> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or name + of the VM. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command discards the saved state file for the VM + called <filename>vm2</filename>. When you next start the VM, the + VM's operating system is restarted. + </para> +<screen>$ VBoxManage discardstate vm2</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-adoptstate"/> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-encryptmedium.xml b/doc/manual/en_US/man_VBoxManage-encryptmedium.xml new file mode 100644 index 00000000..fd2179ca --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-encryptmedium.xml @@ -0,0 +1,174 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage encryptmedium +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-encryptmedium" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage encryptmedium</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-encryptmedium</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-encryptmedium</refname> + <refpurpose>manage a DEK-encrypted medium or image</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-encryptmedium"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage encryptmedium</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>filename</replaceable></arg> + </group> + <arg>--cipher=<replaceable>cipher-ID</replaceable></arg> + <arg>--newpassword=<replaceable>password</replaceable></arg> + <arg>--newpasswordid=<replaceable>password-ID</replaceable></arg> + <arg>--oldpassword=<replaceable>password</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage encryptmedium</command> command enables + you to create and manage a DEK-encrypted medium or image. You can + encrypt an image, decrypt an image, and change the encryption + password of an image. See + <xref linkend="diskencryption-encryption" />. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>filename</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or the + absolute path name of the medium or image to encrypt. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--newpassword=<replaceable>password</replaceable></option></term> + <listitem><para> + Specifies the new encryption password. + <replaceable>password</replaceable> is either the absolute + path name of a password file on the host operating system or + <literal>-</literal>, which prompts you for the password. + </para><para> + You must use the <option>--newpasswordid</option> option + with this <option>--newpassword</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--oldpassword=<replaceable>password</replaceable></option></term> + <listitem><para> + Specifies the original encryption password. + <replaceable>password</replaceable> is either the absolute + path name of a password file on the host operating system or + <literal>-</literal>, which prompts you for the original + password. + </para><para> + This option enables you to gain access to an encrypted + medium or image to do the following: + </para><itemizedlist> + <listitem><para> + Decrypt an encrypted image by using this option by + itself. + </para></listitem> + <listitem><para> + Change the password of the encrypted image by using the + <option>--newpassword</option> option. + </para></listitem> + <listitem><para> + Change the encryption cipher of the image by using the + <option>--cipher</option> option. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--cipher=<replaceable>cipher-ID</replaceable></option></term> + <listitem><para> + Specifies the cipher to use for encryption. Valid values are + <literal>AES-XTS128-PLAIN64</literal> or + <literal>AES-XTS256-PLAIN64</literal>. + </para><para> + This option enables you to set up or change encryption on + the medium or image. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--newpasswordid=<replaceable>password-ID</replaceable></option></term> + <listitem><para> + Specifies a new password identifier that is used for correct + identification when supplying multiple passwords during VM + startup. + </para><para> + If you use the same password and password identifier when + encrypting multiple images, you need to supply the password + only one time during VM startup. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following example shows how to encrypt the + <filename>ol7u4-1.vdi</filename> image by using the + <literal>AES-XTS128-PLAIN64</literal> cipher, specifying a + password identifier of <literal>1001</literal>, and using the + <filename>$HOME/pwfile</filename> password file: + </para> +<screen>$ VBoxManage encryptmedium "$HOME/VirtualBox VMs/ol7u4/ol7u4-1.vdi" \ + --cipher="AES-XTS128-PLAIN64" --newpasswordid="1001" --newpassword=$HOME/pwfile</screen> + <para> + The following example shows how to decrypt an encrypted image + called <filename>ol7u4-2.vdi</filename>: + </para> +<screen>$ VBoxManage encryptmedium "$HOME/VirtualBox VMs/ol7u4/ol7u4-2.vdi" \ + --oldpassword=- + Password: <replaceable>original-password</replaceable></screen> + <para> + The following example shows how to change the password for an + encrypted image called <filename>ol7u4-3.vdi</filename>. The + command reads the original password from the + <filename>$HOME/pwfile.orig</filename> file, reads the new + password from the <filename>$HOME/pwfile</filename> file, and + assigns a password identifier of <literal>1001</literal>. + </para> +<screen>$ VBoxManage encryptmedium "$HOME/VirtualBox VMs/ol7u4/ol7u4-3.vdi" \ + --oldpassword=$HOME/pwfile.orig --newpassword=$HOME/pwfile --newpasswordid="1001"</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-encryptvm.xml b/doc/manual/en_US/man_VBoxManage-encryptvm.xml new file mode 100644 index 00000000..375578a2 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-encryptvm.xml @@ -0,0 +1,204 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage encryptvm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-encryptvm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage encryptvm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-encryptvm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-encryptvm</refname> + <refpurpose>change encryption and passwords of the VM</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-encryptvm-setencryption"> + <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage encryptvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">setencryption</arg> + <arg choice="plain">--old-password <replaceable>file</replaceable></arg> + <arg choice="plain">--cipher <replaceable>cipher-identifier</replaceable></arg> + <arg choice="plain">--new-password <replaceable>file</replaceable></arg> + <arg choice="plain">--new-password-id <replaceable>password-identifier</replaceable></arg> + <arg choice="plain">--force</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-encryptvm-checkpassword"> + <command>VBoxManage encryptvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">checkpassword</arg> + <arg choice="req"><replaceable>file</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-encryptvm-addpassword"> + <command>VBoxManage encryptvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">addpassword</arg> + <arg choice="plain">--password <replaceable>file</replaceable></arg> + <arg choice="plain">--password-id <replaceable>password-identifier</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-encryptvm-removepassword"> + <command>VBoxManage encryptvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">removepassword</arg> + <arg choice="req"><replaceable>password-identifier</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage encryptvm</command> command enables you to + change the encryption or add and remove user passwords for the + virtual machine (VM). The following sections describe the subcommands + that you can use: + </para> + <refsect2 id="vboxmanage-encryptvm-setencryption"> + <title>Set encryption of the Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage encryptvm + <replaceable>vmname</replaceable> setencryption</command> command + changes encryption of a VM. + </para> + <para> + Use the <option>--old-password</option> to supply old encryption + password. Either specify the absolute pathname of a password file + on the host operating system, or <literal>-</literal> to prompt + you for the old password. + </para> + <para> + Use the <option>--cipher</option> option to specify the + new cipher for encryption of the VM. Only <literal>AES-128</literal> + and <literal>AES-256</literal> are supported. Appropriate mode + GCM, CTR or XTS will be selected by VM depending on encrypting + component. + </para> + <para> + Use the <option>--new-password</option> option to specify the + new password for encryption of the VM. Either specify the absolute + pathname of a password file on the host operating system, or + <literal>-</literal> to prompt you for the new password. + </para> + <para> + Use the <option>--new-password-id</option> option to specify the + new id for the password for encryption of the VM. + </para> + <para> + Use the <option>--force</option> option to make the system + to reencrypt the VM instead of simple changing the password. + </para> + </refsect2> + <refsect2 id="vboxmanage-encryptvm-checkpassword"> + <title>Check the supplied password is correct</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage encryptvm + <replaceable>vmname</replaceable> checkpassword</command> command + checks the correctness of the supplied password. + </para> + <para> + The password can be supplied from file. Specify the absolute + pathname of a password file on the host operating system. Also, + you can specify <literal>-</literal> to prompt you for the password. + </para> + </refsect2> + <refsect2 id="vboxmanage-encryptvm-addpassword"> + <title>Add password for decrypting the Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage encryptvm + <replaceable>vmname</replaceable> addpassword</command> command + adds a password for decrypting the VM. + </para> + <para> + Use the <option>--password</option> to supply the encryption + password. Either specify the absolute pathname of a password file + on the host operating system, or <literal>-</literal> to prompt + you for the password. + </para> + <para> + Use the <option>--password-id</option> option to specify the + id the password is supplied for. + </para> + </refsect2> + <refsect2 id="vboxmanage-encryptvm-removepassword"> + <title>Remove password used for decrypting the Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage encryptvm + <replaceable>vmname</replaceable> removepassword</command> command + removes a password used for decrypting the VM. + </para> + <para> + Specify the password identifier for removing. The password becomes + unknown and the VM can not be decrypted. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command encrypts the <filename>ol7</filename> VM using + AES-256 giving password via command prompt: + </para> +<screen>$ VBoxManage encryptvm ol7 setencryption --cipher=AES-256 --new-password - --new-password-id vmid</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-createvm" />, + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-export.xml b/doc/manual/en_US/man_VBoxManage-export.xml new file mode 100644 index 00000000..75a73829 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-export.xml @@ -0,0 +1,441 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage export +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-export" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage export</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-export</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-export</refname> + <refpurpose>export one or more virtual machines to a virtual appliance or to a cloud service</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-export-ovf"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage export</command> + <arg choice="req"><replaceable>machines</replaceable></arg> + <arg choice="req">--output=<replaceable>name</replaceable></arg> + <group> + <arg choice="plain">--legacy09</arg> + <arg choice="plain">--ovf09</arg> + <arg choice="plain">--ovf10</arg> + <arg choice="plain">--ovf20</arg> + </group> + <arg>--manifest</arg> + <arg>--options=<group choice="plain" rep="repeat"> + <arg choice="plain">manifest</arg> + <arg choice="plain">iso</arg> + <arg choice="plain">nomacs</arg> + <arg choice="plain">nomacsbutnat</arg> + </group></arg> + <arg>--vsys=<replaceable>virtual-system-number</replaceable></arg> + <arg>--description=<replaceable>description-info</replaceable></arg> + <arg>--eula=<replaceable>license-text</replaceable></arg> + <arg>--eulafile=<replaceable>filename</replaceable></arg> + <arg>--product=<replaceable>product-name</replaceable></arg> + <arg>--producturl=<replaceable>product-URL</replaceable></arg> + <arg>--vendor=<replaceable>vendor-name</replaceable></arg> + <arg>--vendorurl=<replaceable>vendor-URL</replaceable></arg> + <arg>--version=<replaceable>version-info</replaceable></arg> + <arg>--vmname=<replaceable>vmname</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-export-cloud"> + <command>VBoxManage export</command> + <arg choice="req"><replaceable>machine</replaceable></arg> + <arg choice="req">--output=<replaceable>cloud-service-provider</replaceable></arg> + <arg>--opc10</arg> + <arg>--vmname=<replaceable>vmname</replaceable></arg> + <arg>--cloud=<replaceable>virtual-system-number</replaceable></arg> + <arg>--cloudprofile=<replaceable>cloud-profile-name</replaceable></arg> + <arg>--cloudshape=<replaceable>cloud-shape-name</replaceable></arg> + <arg>--clouddomain=<replaceable>cloud-domain</replaceable></arg> + <arg>--clouddisksize=<replaceable>disk-size-in-GB</replaceable></arg> + <arg>--cloudbucket=<replaceable>bucket-name</replaceable></arg> + <arg>--cloudocivcn=<replaceable>OCI-VCN-ID</replaceable></arg> + <arg>--cloudocisubnet=<replaceable>OCI-subnet-ID</replaceable></arg> + <arg>--cloudkeepobject=<group choice="plain"> + <arg choice="plain">true</arg> + <arg choice="plain">false</arg> + </group></arg> + <arg>--cloudlaunchinstance=<group choice="plain"> + <arg choice="plain">true</arg> + <arg choice="plain">false</arg> + </group></arg> + <arg>--cloudlaunchmode=<group choice="plain"> + <arg choice="plain">EMULATED</arg> + <arg choice="plain">PARAVIRTUALIZED</arg> + </group></arg> + <arg>--cloudpublicip=<group choice="plain"> + <arg choice="plain">true</arg> + <arg choice="plain">false</arg> + </group></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage export</command> command enables you to + export one or more virtual machines (VMs) from &product-name;. You + can export the VM to one of the following: + </para> + <itemizedlist> + <listitem><para> + <emphasis role="bold">Virtual appliance in OVF + format.</emphasis> Includes the copying of its virtual disk + images to compressed VMDK. + </para></listitem> + <listitem><para> + <emphasis role="bold">Cloud service such as &oci;.</emphasis> + Exports a single VM. + </para></listitem> + </itemizedlist> + <para> + For more information about exporting VMs from &product-name;, see + <xref linkend="ovf" /> + </para> + <refsect2 id="vboxmanage-export-ovf"> + <title>Export a Virtual Machine to an OVF Virtual Appliance</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage export</command> command enables you to + export a VM as a virtual appliance in OVF format. + </para> + <variablelist> + <varlistentry> + <term><replaceable>machines</replaceable></term> + <listitem><para> + Specifies a comma-separated list of one or more machines + to export to the same OVF file. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--output=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies the target OVF file. The file can be OVF, OVA, + or a ZIP file compressed with the <command>gzip</command> + command. Because the directory that contains the target + OVF file will also store the exported disk images in the + compressed VMDK format, ensure that this directory has + sufficient disk space in which to store the images. + </para><para> + The short form of this option is <option>-o</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--legacy09</option></term> + <listitem><para> + Exports in OVF 0.9 legacy mode if the virtualization + product is not fully compatible with the OVF 1.0 standard. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ovf09</option></term> + <listitem><para> + Exports in OVF 0.9 format. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ovf10</option></term> + <listitem><para> + Exports in OVF 1.0 format. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ovf20</option></term> + <listitem><para> + Exports in OVF 2.0 format. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--manifest</option></term> + <listitem><para> + Creates a manifest of the exported files. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--options=<replaceable>argument</replaceable>,...</option></term> + <listitem><para> + Specifies information to control the exact content of the + appliance file. Specify one or more comma-separated + arguments: + </para><variablelist> + <varlistentry> + <term><literal>manifest</literal></term> + <listitem><para> + Produces a manifest file that detects corrupted + appliances on import. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>iso</literal></term> + <listitem><para> + Exports DVD images in an ISO file. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>nomacs</literal></term> + <listitem><para> + Excludes all MAC addresses. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>nomacsbutnat</literal></term> + <listitem><para> + Excludes all MAC addresses except for those in a NAT + network. + </para></listitem> + </varlistentry> + </variablelist></listitem> + </varlistentry> + <varlistentry> + <term><option>--description=<replaceable>description-info</replaceable></option></term> + <listitem><para> + Specifies a description of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--eula=<replaceable>license-text</replaceable></option></term> + <listitem><para> + Specifies end-user license text. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--eulafile=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies an end-user license file. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--product=<replaceable>product-name</replaceable></option></term> + <listitem><para> + Specifies a product name. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--producturl=<replaceable>product-URL</replaceable></option></term> + <listitem><para> + Specifies a product URL. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vendor=<replaceable>vendor-name</replaceable></option></term> + <listitem><para> + Specifies a vendor name. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vendorurl=<replaceable>vendor-URL</replaceable></option></term> + <listitem><para> + Specifies a vendor URL. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--version=<replaceable>version-info</replaceable></option></term> + <listitem><para> + Specifies version information. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vmname=<replaceable>vmname</replaceable></option></term> + <listitem><para> + Specifies the name of the exported VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vsys=<replaceable>virtual-system-number</replaceable></option></term> + <listitem><para> + Specifies the number of the virtual system. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-export-cloud"> + <title>Export a Virtual Machine to &oci;</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage export</command> command enables you to + export a VM to a cloud service provider such as &oci;. By + default, the exported disk image is converted into compressed VMDK + format. This minimizes the amount of data to transfer to the cloud + service. + </para> + <para> + Some of the following options are configuration settings for the + VM instance. As a result, specify an Oracle Cloud Identifier + (OCID) for a resource. Use the &oci; Console to view OCIDs. + </para> + <variablelist> + <varlistentry> + <term><option>--output=<replaceable>cloud-service-provider</replaceable></option></term> + <listitem><para> + Specifies the short name of the cloud service provider to + which you export the VM. For &oci;, specify + <literal>OCI://</literal>. + </para><para> + The short form of this option is <option>-o</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--opc10</option></term> + <listitem><para> + Exports in &oci; format. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloud=<replaceable>number-of-virtual-system</replaceable></option></term> + <listitem><para> + Specifies a number that identifies the VM to export. + Numbering starts at <literal>0</literal> for the first VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vmname=<replaceable>vmname</replaceable></option></term> + <listitem><para> + Specifies the name of the exported VM, which is used as + the VM instance name in &oci;. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudprofile=<replaceable>cloud-profile-name</replaceable></option></term> + <listitem><para> + Specifies the cloud profile to use to connect to the cloud + service provider. The cloud profile contains your &oci; + account details, such as your user OCID and the + fingerprint for your public key. + </para><para> + To use a cloud profile, you must have the required + permissions on &oci;. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudshape=<replaceable>cloud-shape-name</replaceable></option></term> + <listitem><para> + Specifies the shape used by the VM instance. The shape + defines the number of CPUs and the amount of memory that + is allocated to the VM instance. Ensure that the shape is + compatible with the exported image. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--clouddomain=<replaceable>cloud-domain</replaceable></option></term> + <listitem><para> + Specifies the availability domain to use for the VM + instance. Enter the full name of the availability domain. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--clouddisksize=<replaceable>disk-size-in-GB</replaceable></option></term> + <listitem><para> + Specifies the amount of disk space, in gigabytes, to use + for the exported disk image. Valid values are from 50 GB + to 300 GB. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudbucket=<replaceable>bucket-name</replaceable></option></term> + <listitem><para> + Specifies the bucket in which to store uploaded files. In + &oci;, a bucket is a logical container for storing + objects. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudocivcn=<replaceable>OCI-VCN-ID</replaceable></option></term> + <listitem><para> + Specifies the OCID of the virtual cloud network (VCN) to + use for the VM instance. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudocisubnet=<replaceable>OCI-subnet-ID</replaceable></option></term> + <listitem><para> + Specifies the OCID of the VCN subnet to use for the VM + instance. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudkeepobject=true | false</option></term> + <listitem><para> + Specifies whether to store the exported disk image in + Oracle Object Storage. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudlaunchinstance=true | false</option></term> + <listitem><para> + Specifies whether to start the VM instance after the + export to &oci; completes. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudlaunchinstance=EMULATED | PARAVIRTUALIZED</option></term> + <listitem><para> + Specifies the launch mode used for the instance. + Paravirtualized mode gives improved performance. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudpublicip=true | false</option></term> + <listitem><para> + Specifies whether to enable a public IP address for the VM + instance. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Example</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following example shows how to export the + <literal>myVM</literal> VM to &oci;. The command's option + arguments describe the configuration of the + <literal>myVM_Cloud</literal> VM in &oci;. + </para> +<screen># VBoxManage export myVM --output=OCI:// --cloud=0 --vmname=myVM_Cloud \ +--cloudprofile="standard user" --cloudbucket=myBucket \ +--cloudshape=VM.Standard2.1 --clouddomain=US-ASHBURN-AD-1 --clouddisksize=50 \ +--cloudocivcn=ocid1.vcn.oc1.iad.aaaa... --cloudocisubnet=ocid1.subnet.oc1.iad.aaaa... \ +--cloudkeepobject=true --cloudlaunchinstance=true --cloudpublicip=true</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-extpack.xml b/doc/manual/en_US/man_VBoxManage-extpack.xml new file mode 100644 index 00000000..08f10d63 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-extpack.xml @@ -0,0 +1,158 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage extpack +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-extpack" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage extpack</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-extpack</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-extpack</refname> + <refpurpose>extension package management</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-extpack-install"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage extpack install</command> + <arg>--replace</arg> + <arg>--accept-license=<replaceable>sha256</replaceable></arg> + <arg choice="req"><replaceable>tarball</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-extpack-uninstall"> + <command>VBoxManage extpack uninstall</command> + <arg>--force</arg> + <arg choice="req"><replaceable>name</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-extpack-cleanup"> + <command>VBoxManage extpack cleanup</command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <refsect2 id="vboxmanage-extpack-install"> + <title>extpack install</title> + <remark role="help-copy-synopsis"/> + <para> + Installs a new extension pack on the system. This command will fail if an older + version of the same extension pack is already installed. The + <option>--replace</option> option can be used to uninstall any + old package before the new one is installed. + </para> + <variablelist> + <varlistentry> + <term><option>--replace</option></term><listitem><para>Uninstall existing extension pack version.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--accept-license=<replaceable>sha256</replaceable></option></term> + <listitem> + <para>Accept the license text with the given SHA-256 hash value.</para> + <para>VBoxManage will display the SHA-256 value when performing a manual + installation. The hash can of course be calculated by looking inside + the extension pack and using sha256sum or similar on the license file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><replaceable>tarball</replaceable></term> + <listitem> + <para>The file containing the extension pack to be installed.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-extpack-uninstall"> + <title>extpack uninstall</title> + <remark role="help-copy-synopsis"/> + <para> + Uninstalls an extension pack from the system. The subcommand will also succeed + in the case where the specified extension pack is not present on the system. + You can use <computeroutput>VBoxManage list extpacks</computeroutput> to show + the names of the extension packs which are currently installed. + </para> + <variablelist> + <varlistentry> + <term><option>--force</option></term> + <listitem> + <para>Overrides most refusals to uninstall an extension pack</para> + </listitem> + </varlistentry> + <varlistentry> + <term><replaceable>name</replaceable></term> + <listitem> + <para>The name of the extension pack to be uninstalled.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-extpack-cleanup"> + <title>extpack cleanup</title> + <remark role="help-copy-synopsis"/> + <para> + Used to remove temporary files and directories that may have been left behind + if a previous install or uninstall command failed. + </para> + </refsect2> + + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="EXTPACK_UNINSTALL,EXTPACK"/> + <para> + How to list extension packs: +<screen>$ VBoxManage list extpacks +Extension Packs: 1 +Pack no. 0: Oracle VM VirtualBox Extension Pack +Version: 4.1.12 +Revision: 77218 +Edition: +Description: USB 2.0 Host Controller, VirtualBox RDP, PXE ROM with E1000 support. +VRDE Module: VBoxVRDP +Usable: true +Why unusable:</screen></para> + + <para>How to remove an extension pack: +<screen>$ VBoxManage extpack uninstall "Oracle VM VirtualBox Extension Pack" +0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100% +Successfully uninstalled "Oracle VM VirtualBox Extension Pack".</screen></para> + </refsect1> + +</refentry> + diff --git a/doc/manual/en_US/man_VBoxManage-getextradata.xml b/doc/manual/en_US/man_VBoxManage-getextradata.xml new file mode 100644 index 00000000..bb032dd0 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-getextradata.xml @@ -0,0 +1,151 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage getextradata +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-getextradata" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-18 00:40:56 +0100 (Wed, 18 Jan 2023) $</pubdate> + <title>VBoxManage getextradata</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-getextradata</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-getextradata</refname> + <refpurpose>view keyword values that are associated with a virtual machine or + configuration</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-getextradata"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage getextradata</command> + <group choice="req"> + <arg choice="plain">global</arg> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <group choice="plain"> + <arg choice="req"><replaceable>keyword</replaceable></arg> + <arg>enumerate</arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage getextradata</command> command enables you + to retrieve keyword data that is associated with a virtual machine + (VM) or with an &product-name; configuration. + </para> + <variablelist> + <varlistentry> + <term><literal>global</literal></term> + <listitem><para> + Specifies to retrieve information about the configuration + rather than a VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or name + of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>enumerate</literal></term> + <listitem><para> + Shows all keyword values for the specified VM or + configuration. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>keyword</replaceable></term> + <listitem><para> + Specifies the keyword for which to retrieve its value. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following command retrieves the <literal>installdate</literal> + keyword value for the <literal>Fedora5</literal> VM: + </para> +<screen>$ VBoxManage getextradata Fedora5 installdate +VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable> +Copyright (C) 2005-2023 Oracle and/or its affiliates + +Value: 2006.01.01</screen> + <para> + The following command retrieves the information for all keywords + of the <literal>OracleLinux7u4</literal> VM: + </para> +<screen>$ VBoxManage getextradata OracleLinux7u4 enumerate +Key: GUI/LastCloseAction, Value: PowerOff +Key: GUI/LastGuestSizeHint, Value: 1048,696 +Key: GUI/LastNormalWindowPosition, Value: 851,286,1048,738</screen> + <para> + The following command retrieves the information for all keywords + in the configuration: + </para> +<screen>$ VBoxManage getextradata global enumerate +Key: GUI/Details/Elements, Value: general,system,preview,display,storage,audio,network,usb,sharedFolders,description +Key: GUI/DetailsPageBoxes, Value: general,system,preview,display,storage,audio,network,usb,sharedFolders,description +Key: GUI/GroupDefinitions/, Value: m=43349dd8-2aa3-41b8-988f-0e255ce68090,m=9ebcd81e-5231-48ce-a27d-28218757f3fe,m=c690e8b1-93a0-4c95-9cd7-6437fff93251,m=f7c1e10d-3722-4891-887e-07b3c4104946 +Key: GUI/HideDescriptionForWizards, Value: NewVM +Key: GUI/LastItemSelected, Value: m=ol7u4 +Key: GUI/LastWindowPosition, Value: 951,510,960,520 +Key: GUI/RecentFolderCD, Value: C:/Users/user1 +Key: GUI/RecentListCD, Value: C:\Users\user1\V1.iso,C:\Users\user1\V2.iso,C:\Users\user1\V3.iso +Key: GUI/SplitterSizes, Value: 318,637 +Key: GUI/SuppressMessages, Value: remindAboutMouseIntegration,remindAboutAutoCapture +Key: GUI/Toolbar/MachineTools/Order, Value: Details +Key: GUI/Tools/LastItemsSelected, Value: Welcome,Details +Key: GUI/UpdateCheckCount, Value: 71 +Key: GUI/UpdateDate, Value: 1 d, 2019-04-10, stable, 5.2.22 +Key: GUI/VirtualMediaManager/Details/Expanded, Value: true</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-setextradata" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-guestcontrol.xml b/doc/manual/en_US/man_VBoxManage-guestcontrol.xml new file mode 100644 index 00000000..5f4bf901 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-guestcontrol.xml @@ -0,0 +1,1351 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage guestcontrol +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-guestcontrol" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-08-08 17:18:00 +0200 (Tue, 08 Aug 2023) $</pubdate> + <title>VBoxManage guestcontrol</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-guestcontrol</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-guestcontrol</refname> + <refpurpose>control a virtual machine from the host system</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-run"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">run</arg> + <arg>--arg0=<replaceable>argument 0</replaceable></arg> + <arg>--domain=<replaceable>domainname</replaceable></arg> + <arg>--dos2unix</arg> + <arg>--exe=<replaceable>filename</replaceable></arg> + <arg>--ignore-orphaned-processes</arg> + <group> + <arg choice="plain">--no-wait-stderr</arg> + <arg choice="plain">--wait-stderr</arg> + </group> + <group> + <arg choice="plain">--no-wait-stdout</arg> + <arg choice="plain">--wait-stdout</arg> + </group> + <group> + <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg> + <arg choice="plain">--password=<replaceable>password</replaceable></arg> + </group> + <arg>--profile</arg> + <arg>--putenv=<replaceable>var-name</replaceable>=[<replaceable>value</replaceable>]</arg> + <arg>--quiet</arg> + <arg>--timeout=<replaceable>msec</replaceable></arg> + <arg>--unix2dos</arg> + <arg>--unquoted-args</arg> + <arg>--username=<replaceable>username</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req">--<arg rep="repeat"><replaceable>argument</replaceable></arg></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-start"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">start</arg> + <arg>--arg0=<replaceable>argument 0</replaceable></arg> + <arg>--domain=<replaceable>domainname</replaceable></arg> + <arg>--exe=<replaceable>filename</replaceable></arg> + <arg>--ignore-orphaned-processes</arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg> + <arg choice="plain">--password=<replaceable>password</replaceable></arg> + </group> + <arg>--profile</arg> + <arg>--putenv=<replaceable>var-name</replaceable>=[<replaceable>value</replaceable>]</arg> + <arg>--quiet</arg> + <arg>--timeout=<replaceable>msec</replaceable></arg> + <arg>--unquoted-args</arg> + <arg>--username=<replaceable>username</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req">--<arg rep="repeat"><replaceable>argument</replaceable></arg></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-copyfrom"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">copyfrom</arg> + <arg>--dereference</arg> + <arg>--domain=<replaceable>domainname</replaceable></arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg> + <arg choice="plain">--password=<replaceable>password</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--no-replace</arg> + <arg>--recursive</arg> + <arg>--target-directory=<replaceable>host-destination-dir</replaceable></arg> + <arg>--update</arg> + <arg>--username=<replaceable>username</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req"><replaceable>guest-source0</replaceable></arg> + <arg choice="plain"><replaceable>guest-source1</replaceable> [...]</arg> + <arg choice="req"><replaceable>host-destination</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-copyto"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">copyto</arg> + <arg>--dereference</arg> + <arg>--domain=<replaceable>domainname</replaceable></arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg> + <arg choice="plain">--password=<replaceable>password</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--no-replace</arg> + <arg>--recursive</arg> + <arg>--target-directory=<replaceable>guest-destination-dir</replaceable></arg> + <arg>--update</arg> + <arg>--username=<replaceable>username</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req"><replaceable>host-source0</replaceable></arg> + <arg choice="plain"><replaceable>host-source1</replaceable> [...]</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-mkdir"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">mkdir</arg> + <arg>--domain=<replaceable>domainname</replaceable></arg> + <arg>--mode=<replaceable>mode</replaceable></arg> + <arg>--parents</arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg> + <arg choice="plain">--password=<replaceable>password</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--username=<replaceable>username</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req" rep="repeat"><replaceable>guest-directory</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-rmdir"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">rmdir</arg> + <arg>--domain=<replaceable>domainname</replaceable></arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg> + <arg choice="plain">--password=<replaceable>password</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--recursive</arg> + <arg>--username=<replaceable>username</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req" rep="repeat"><replaceable>guest-directory</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-rm"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">rm</arg> + <arg>--domain=<replaceable>domainname</replaceable></arg> + <arg>--force</arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg> + <arg choice="plain">--password=<replaceable>password</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--username=<replaceable>username</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req" rep="repeat"><replaceable>guest-directory</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-mv"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">mv</arg> + <arg>--domain=<replaceable>domainname</replaceable></arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg> + <arg choice="plain">--password=<replaceable>password</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--username=<replaceable>username</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req" rep="repeat"><replaceable>source</replaceable></arg> + <arg choice="req"><replaceable>destination-directory</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-mktemp"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">mktemp</arg> + <arg>--directory</arg> + <arg>--domain=<replaceable>domainname</replaceable></arg> + <arg>--mode=<replaceable>mode</replaceable></arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg> + <arg choice="plain">--password=<replaceable>password</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--secure</arg> + <arg>--tmpdir=<replaceable>directory-name</replaceable></arg> + <arg>--username=<replaceable>username</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req"><replaceable>template-name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-stat"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">stat</arg> + <arg>--domain=<replaceable>domainname</replaceable></arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg> + <arg choice="plain">--password=<replaceable>password</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--username=<replaceable>username</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req"><replaceable>filename</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-list"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">list</arg> + <group choice="req"> + <arg choice="plain">all</arg> + <arg choice="plain">files</arg> + <arg choice="plain">processes</arg> + <arg choice="plain">sessions</arg> + </group> + <arg>--quiet</arg> + <arg>--verbose</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-closeprocess"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">closeprocess</arg> + <group> + <arg choice="plain">--session-id=<replaceable>ID</replaceable></arg> + <arg choice="plain">--session-name=<replaceable>name-or-pattern</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--verbose</arg> + <arg choice="req" rep="repeat"><replaceable>PID</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-closesession"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">closesession</arg> + <group> + <arg choice="plain">--all</arg> + <arg choice="plain">--session-id=<replaceable>ID</replaceable></arg> + <arg choice="plain">--session-name=<replaceable>name-or-pattern</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--verbose</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-updatega"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">updatega</arg> + <arg>--quiet</arg> + <arg>--verbose</arg> + <arg>--source=<replaceable>guest-additions.ISO</replaceable></arg> + <arg>--wait-start</arg> + <arg>-- <arg rep="repeat"><replaceable>argument</replaceable></arg></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-watch"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">watch</arg> + <arg>--quiet</arg> + <arg>--verbose</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage guestcontrol</command> command enables you + to control a guest (VM) from the host system. See + <xref linkend="guestadd-guestcontrol" />. + </para> + <refsect2> + <title>Common Options and Operands</title> + <para> + The following options can be used by any of the + <command>VBoxManage guestcontrol</command> subcommands: + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or name + of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--quiet</option></term> + <listitem><para> + Specifies that the command produce quieter output. + </para><para> + The short form of this option is <option>-q</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--verbose</option></term> + <listitem><para> + Specifies that the command produce more detailed output. + </para><para> + The short form of this option is <option>-v</option>. + </para></listitem> + </varlistentry> + </variablelist> + <para> + Some of the <command>VBoxManage guestcontrol</command> + subcommands require that you provide guest credentials for + authentication. The subcommands are: + <command>copyfrom</command>, <command>copyto</command>, + <command>mkdir</command>, <command>mktemp</command>, + <command>mv</command>, <command>rmdir</command>, + <command>rm</command>, <command>run</command>, + <command>start</command>, and <command>stat</command>. + </para> + <para> + While you cannot perform anonymous executions, a user account + password is optional and depends on the guest's OS security + policy. If a user account does not have an associated password, + specify an empty password. On OSes such as Windows, you might + need to adjust the security policy to permit user accounts with + an empty password. In additional, global domain rules might + apply and therefore cannot be changed. + </para> + <para> + The following options are used for authentication on the guest + VM: + </para> + <variablelist> + <varlistentry> + <term><option>--domain=<replaceable>domainname</replaceable></option></term> + <listitem><para> + Specifies the user domain for Windows guest VMs. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password=<replaceable>password</replaceable></option></term> + <listitem><para> + Specifies the password for the specified user. If you do + not specify a password on the command line or if the + password file is empty, the specified user needs to have + an empty password. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--passwordfile=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies the absolute path to a file on the guest OS that + contains the password for the specified user. If the + password file is empty or if you do not specify a password + on the command line, the specified user needs to have an + empty password. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--username=<replaceable>username</replaceable></option></term> + <listitem><para> + Specifies an existing user on the guest OS that runs the + process. If unspecified, the host user runs the process. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2> + <title>Guest Process Restrictions</title> + <para> + By default, you can run up to five guest processes + simultaneously. If a new guest process starts and would exceed + this limit, the oldest not-running guest process is discarded to + run the new process. You cannot retrieve output from a discarded + guest process. If all five guest processes are active and + running, attempting to start a new guest process fails. + </para> + <para> + You can modify the guest process execution limit in two ways: + </para> + <itemizedlist> + <listitem><para> + Use the <command>VBoxManage setproperty</command> command to + update the + <literal>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</literal> + guest property value. + </para></listitem> + <listitem><para> + Use the <command>VBoxService</command> command and specify + the + <option>--control-procs-max-kept=<replaceable>value</replaceable></option> + option. + </para></listitem> + </itemizedlist> + <para> + After you change the limit, you must restart the guest OS. + </para> + <para> + You can serve an unlimited number guest processes by specifing a + value of <literal>0</literal>, however this action is not + recommended. + </para> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-run"> + <title>Run a Command on the guest</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> run</command> command enables + you to execute a program on the guest VM. Standard input, + standard output, and standard error are redirected from the VM + to the host system until the program completes. + </para> + <note> + <para> + The Windows OS imposes certain limitations for graphical + applications. See <xref linkend="KnownIssues" />. + </para> + </note> + <variablelist> + <varlistentry> + <term><option>--exe=<replaceable>path-to-executable</replaceable></option></term> + <listitem><para> + Specifies the absolute path of the executable program to + run on the guest VM. For example: + <filename>C:\Windows\System32\calc.exe</filename>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--timeout=<replaceable>msec</replaceable></option></term> + <listitem><para> + Specifies the maximum amount of time, in milliseconds, + that the program can run. While the program runs, + <command>VBoxManage</command> receives its output. + </para><para> + If you do not specify a timeout value, + <command>VBoxManage</command> waits indefinitely for the + process to end, or for an error to occur. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--putenv=<replaceable>NAME</replaceable>=[<replaceable>value</replaceable>]</option></term> + <listitem><para> + Sets, modifies, and unsets environment variables in the + guest VM environment. + </para><para> + When you create a guest process, it runs with the default + standard guest OS environment. Use this option to modify + environment variables in that default environment. + </para><para> + Use the + <option>--putenv=<replaceable>NAME</replaceable>=[<replaceable>value</replaceable>]</option> + option to set or modify the environment variable specified + by <replaceable>NAME</replaceable>. + </para><para> + Use the + <option>--putenv=<replaceable>NAME</replaceable>=[<replaceable>value</replaceable>]</option> + option to unset the environment variable specified by + <replaceable>NAME</replaceable>. + </para><para> + Ensure that any environment variable name or value that + includes spaces is enclosed by quotes. + </para><para> + Specify a <option>--putenv</option> option for each + environment variable that you want to modify. + </para><para> + The short form of this option is <option>-E</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unquoted-args</option></term> + <listitem><para> + Disables the escaped double quoting of arguments that you + pass to the program. For example, + <literal>\"fred\"</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ignore-orphaned-processes</option></term> + <listitem><para> + Ignores orphaned processes. Not yet implemented. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--profile</option></term> + <listitem><para> + Uses a shell profile to specify the environment to use. + Not yet implemented. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--no-wait-stdout</option></term> + <listitem><para> + Does not wait for the guest process to end or receive its + exit code and any failure explanation. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--wait-stdout</option></term> + <listitem><para> + Waits for the guest process to end to receive its exit + code and any failure explanation. The + <command>VBoxManage</command> command receives the + standard output of the guest process while the process + runs. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--no-wait-stderr</option></term> + <listitem><para> + Does not wait for the guest process to end to receive its + exit code, error messages, and flags. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--wait-stderr</option></term> + <listitem><para> + Waits for the guest process to end to receive its exit + code, error messages, and flags. The + <command>VBoxManage</command> command receives the + standard error of the guest process while the process + runs. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dos2unix</option></term> + <listitem><para> + Transform DOS or Windows guest output to UNIX or Linux + output. This transformation changes CR + LF line endings + to LF. Not yet implemented. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unix2dos</option></term> + <listitem><para> + Transform UNIX or Linux guest output to DOS or Windows + output. This transformation changes LF line endings to CR + + LF. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--[<replaceable>argument</replaceable>...]</option></term> + <listitem><para> + Specifies the name of the program and any arguments to + pass to the program. + </para><para> + Ensure that any command argument that includes spaces is + enclosed by quotes. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-start"> + <title>Start a Command on the guest</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> start</command> command + enables you to execute a guest program until it completes. + </para> + <note> + <para> + The Windows OS imposes certain limitations for graphical + applications. See <xref linkend="KnownIssues" />. + </para> + </note> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-copyfrom"> + <title>Copy a file from the guest to the host.</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> copyfrom</command> command + enables you to copy a file from the guest VM to the host system. + </para> + <variablelist> + <varlistentry> + <term><option>--dereference</option></term> + <listitem><para> + Enables following of symbolic links on the guest file + system. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--no-replace</option></term> + <listitem><para> + Only copies a file if it does not exist on the host yet. + </para><para> + The short form of this option is <option>-n</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recursive</option></term> + <listitem><para> + Recursively copies files and directories from the + specified guest directory to the host. + </para><para> + The short form of this option is <option>-R</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--target-directory=<replaceable>host-dst-dir</replaceable></option></term> + <listitem><para> + Specifies the absolute path of the destination directory + on the host system. For example, + <filename>C:\Temp</filename>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--update</option></term> + <listitem><para> + Only copies a file if the guest file is newer than on the host. + </para><para> + The short form of this option is <option>-u</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal><replaceable>guest-source0</replaceable> [<replaceable>guest-source1</replaceable> [...]]</literal></term> + <listitem><para> + Specifies the absolute path of one or more files to copy + from the guest VM. For example, + <filename>C:\Windows\System32\calc.exe</filename>. You can + use wildcards to specify multiple files. For example, + <filename>C:\Windows\System*\*.dll</filename>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-copyto"> + <title>Copy a file from the host to the guest.</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> copyto</command> command + enables you to copy a file from the host system to the guest VM. + </para> + <variablelist> + <varlistentry> + <term><option>--dereference</option></term> + <listitem><para> + Enables following of symbolic links on the host system. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--no-replace</option></term> + <listitem><para> + Only copies a file if it does not exist on the guest yet. + </para><para> + The short form of this option is <option>-n</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recursive</option></term> + <listitem><para> + Recursively copies files and directories from the + specified host directory to the guest. + </para><para> + The short form of this option is <option>-R</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--target-directory=<replaceable>guest-dst-dir</replaceable></option></term> + <listitem><para> + Specifies the absolute path of the destination directory + on the guest. For example, + <filename>/home/myuser/fromhost</filename>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--update</option></term> + <listitem><para> + Only copies a file if the host file is newer than on the guest. + </para><para> + The short form of this option is <option>-u</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal><replaceable>host-source0</replaceable> [<replaceable>host-source1</replaceable> [...]]</literal></term> + <listitem><para> + Specifies the absolute path of a file to + copy from the host system. For example, + <filename>C:\Windows\System32\calc.exe</filename>. You can + use wildcards to specify multiple files. For example, + <filename>C:\Windows\System*\*.dll</filename>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-mkdir"> + <title>Create a directory on the guest.</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> mkdir</command> command + enables you to create one or more directories on the guest VM. + </para> + <para> + Alternate forms of this subcommand are <command>md</command>, + <command>createdir</command>, and + <command>createdirectory</command>. + </para> + <variablelist> + <varlistentry> + <term><option>--parents</option></term> + <listitem><para> + Creates any of the missing parent directories of the + specified directory. + </para><para> + For example, if you attempt to create the + <filename>D:\Foo\Bar</filename> directory and the + <filename>D:\Foo</filename> directory does not exist, + using the <option>--parents</option> creates the missing + <filename>D:\Foo</filename> directory. However, if you + attempt to create the <filename>D:\Foo\Bar</filename> and + do not specify the <option>--parents</option> option, the + command fails. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mode=<replaceable>mode</replaceable></option></term> + <listitem><para> + Specifies the permission mode to use for the specified + directory. If you specify the <option>--parents</option> + option, the mode is used for the associated parent + directories, as well. <replaceable>mode</replaceable> is a + four-digit octal mode such as <literal>0755</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal><replaceable>guest-dir</replaceable> [<replaceable>guest-dir</replaceable>...]</literal></term> + <listitem><para> + Specifies an absolute path of one or more directories to + create on the guest VM. For example, + <filename>D:\Foo\Bar</filename>. + </para><para> + If all of the associated parent directories do not exist + on the guest VM, you must specify the + <option>--parents</option> option. + </para><para> + You must have sufficient rights on the guest VM to create + the specified directory and its parent directories. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-rmdir"> + <title>Remove a directory from the guest.</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> rmdir</command> command + enables you to delete the specified directory from the guest VM. + </para> + <para> + Alternate forms of this subcommand are + <command>removedir</command> and + <command>removedirectory</command>. + </para> + <variablelist> + <varlistentry> + <term><option>--recursive</option></term> + <listitem><para> + Recursively removes directories from the specified from + the guest VM. + </para><para> + The short form of this option is <option>-R</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal><replaceable>guest-dir</replaceable> [<replaceable>guest-dir</replaceable>...]</literal></term> + <listitem><para> + Specifies an absolute path of one or more directories to + remove from the guest VM. You can use wildcards to specify + the directory names. For example, + <filename>D:\Foo\*Bar</filename>. + </para><para> + You must have sufficient rights on the guest VM to remove + the specified directory and its parent directories. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-rm"> + <title>Remove a file from the guest.</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> rm</command> command enables + you to delete the specified files from the guest VM. + </para> + <para> + The alternate form of this subcommand is + <command>removefile</command>. + </para> + <variablelist> + <varlistentry> + <term><option>--force</option></term> + <listitem><para> + Forces the operation and overrides any confirmation + requests. + </para><para> + The short form of this option is <option>-f</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal><replaceable>guest-file</replaceable> [<replaceable>guest-file</replaceable>...]</literal></term> + <listitem><para> + Specifies an absolute path of one or more file to remove + from the guest VM. You can use wildcards to specify the + file names. For example, + <filename>D:\Foo\Bar\text*.txt</filename>. + </para><para> + You must have sufficient rights on the guest VM to remove + the specified file. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-mv"> + <title>Rename a file or Directory on the guest</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> mv</command> command enables + you to rename files and directories on the guest VM. + </para> + <para> + Alternate forms of this subcommand are <command>move</command>, + <command>ren</command>, and <command>rename</command>. + </para> + <variablelist> + <varlistentry> + <term><literal><replaceable>guest-source</replaceable> [<replaceable>guest-source</replaceable>...]</literal></term> + <listitem><para> + Specifies an absolute path of a file or a single directory + to move or rename on the guest VM. You can use wildcards + to specify the file names. + </para><para> + You must have sufficient rights on the guest VM to access + the specified file or directory. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>dest</replaceable></term> + <listitem><para> + Specifies the absolute path of the renamed file or + directory, or the destination directory to which to move + the files. If you move only one file, + <replaceable>dest</replaceable> can be a file or a + directory, otherwise <replaceable>dest</replaceable> must + be a directory. + </para><para> + You must have sufficient rights on the guest VM to access + the destination file or directory. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-mktemp"> + <title>Create a Temporary File or Directory on the guest</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> mktemp</command> command + enables you to create a temporary file or temporary directory on + the guest VM. You can use this command to assist with the + subsequent copying of files from the host system to the guest + VM. By default, this command creates the file or directory in + the guest VM's platform-specific <filename>temp</filename> + directory. + </para> + <para> + Alternate forms of this subcommand are + <command>createtemp</command> and + <command>createtemporary</command>. + </para> + <variablelist> + <varlistentry> + <term><option>--directory</option></term> + <listitem><para> + Creates a temporary directory that is specified by the + <replaceable>template</replaceable> operand. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--secure</option></term> + <listitem><para> + Enforces secure file and directory creation by setting the + permission mode to <literal>0755</literal>. Any operation + that cannot be performed securely fails. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mode=<replaceable>mode</replaceable></option></term> + <listitem><para> + Specifies the permission mode to use for the specified + directory. <replaceable>mode</replaceable> is a four-digit + octal mode such as <literal>0755</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tmpdir=<replaceable>directory</replaceable></option></term> + <listitem><para> + Specifies the absolute path of the directory on the guest + VM in which to create the specified file or directory. If + unspecified, <replaceable>directory</replaceable> is the + platform-specific <filename>temp</filename> directory. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>template</replaceable></term> + <listitem><para> + Specifies a template file name for the temporary file, + without a directory path. The template file name must + contain at least one sequence of three consecutive X + characters, or must end in X. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-stat"> + <title>Show a file or File System Status on the guest</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> stat</command> command enables + you to show the status of files or file systems on the guest VM. + </para> + <variablelist> + <varlistentry> + <term><literal><replaceable>file</replaceable> [<replaceable>file</replaceable> ...]</literal></term> + <listitem><para> + Specifies an absolute path of a file or file system on the + guest VM. For example, + <filename>/home/foo/a.out</filename>. + </para><para> + You must have sufficient rights on the guest VM to access + the specified files or file systems. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-list"> + <title>List the Configuration and Status Information for a Guest Virtual + Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> list</command> command enables + you to list guest control configuration and status information. + For example, the output shows open guest sessions, guest + processes, and files. + </para> + <variablelist> + <varlistentry> + <term><literal>all</literal>|<literal>sessions</literal>|<literal>processes</literal>|<literal>files</literal></term> + <listitem><para> + Indicates the type of information to show. + <literal>all</literal> shows all available data, + <literal>sessions</literal> shows guest sessions, + <literal>processes</literal> shows processes, and + <literal>files</literal> shows files. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-closeprocess"> + <title>Terminate a Process in a guest Session</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> closeprocess</command> command + enables you to terminate a guest process that runs in a guest + session. Specify the process by using a process identifier (PID) + and the session by using the session ID or name. + </para> + <variablelist> + <varlistentry> + <term><option>--session-id=<replaceable>ID</replaceable></option></term> + <listitem><para> + Specifies the ID of the guest session. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--session-name=<replaceable>name</replaceable>|<replaceable>pattern</replaceable></option></term> + <listitem><para> + Specifies the name of the guest session. Use a pattern + that contains wildcards to specify multiple sessions. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal><replaceable>PID</replaceable> [<replaceable>PID</replaceable> ...]</literal></term> + <listitem><para> + Specifies the list of PIDs of guest processes to + terminate. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-closesession"> + <title>Close a guest Session</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> closesession</command> command + enables you to close a guest session. Specify the guest session + either by session ID or by name. + </para> + <variablelist> + <varlistentry> + <term><option>--session-id=<replaceable>ID</replaceable></option></term> + <listitem><para> + Specifies the ID of the guest session. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--session-name=<replaceable>name</replaceable>|<replaceable>pattern</replaceable></option></term> + <listitem><para> + Specifies the name of the guest session. Use a pattern + that contains wildcards to specify multiple sessions. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--all</option></term> + <listitem><para> + Closes all guest sessions. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-updatega"> + <title>Update the Guest Additions Software on the guest</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> updatega</command> command + enables you to update the Guest Additions software installed in + the specified guest VM. + </para> + <para> + Alternate forms of this subcommand are + <command>updateadditions</command> and + <command>updateguestadditions</command>. + </para> + <variablelist> + <varlistentry> + <term><option>--source=<replaceable>new-iso-path</replaceable></option></term> + <listitem><para> + Specifies the absolute path of the Guest Additions update + <filename>.ISO</filename> file on the guest VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--reboot</option></term> + <listitem><para> + Automatically reboots the guest after a successful Guest Additions + update. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--timeout=<replaceable>ms</replaceable></option></term> + <listitem><para> + Sets the timeout (in ms) to wait for the overall Guest Additions update + to complete. By default no timeout is being used. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--verify</option></term> + <listitem><para> + Verifies whether the Guest Additions were updated successfully after + a successful installation. A guest reboot is mandatory. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--wait-ready</option></term> + <listitem><para> + Waits for the current Guest Additions being ready to handle the + Guest Additions update. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--wait-start</option></term> + <listitem><para> + Starts the <command>VBoxManage</command> update process on + the guest VM and then waits for the Guest Additions update + to begin before terminating the + <command>VBoxManage</command> process. + </para><para> + By default, the <command>VBoxManage</command> command + waits for the Guest Additions update to complete before it + terminates. Use this option when a running + <command>VBoxManage</command> process affects the + interaction between the installer and the guest OS. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>-- <replaceable>argument</replaceable> [<replaceable>argument</replaceable> ...]</option></term> + <listitem><para> + Specifies optional command-line arguments to pass to the + Guest Additions updater. You might use the + <option>--</option> option to pass the appropriate updater + arguments to retrofit features that are not yet installed. + </para><para> + Ensure that any command argument that includes spaces is + enclosed by quotes. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-waitrunlevel"> + <title>Wait for a guest run level</title> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> waitrunlevel</command> command + enables you to wait for a guest run level being reached. + </para> + <variablelist> + <varlistentry> + <term><option>--timeout=<replaceable>ms</replaceable></option></term> + <listitem><para> + Sets the timeout (in ms) to wait for reaching the run level. + By default no timeout is being used. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option><replaceable>system</replaceable>|<replaceable>userland</replaceable>|<replaceable>desktop</replaceable></option></term> + <listitem><para> + Specifies the run level to wait for. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-watch"> + <title>Show Current Guest Control Activity</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> watch</command> command + enables you to show current guest control activity. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following <command>VBoxManage guestcontrol run</command> + command executes the <command>ls -l /usr</command> command on the + <literal>My OL VM</literal> Oracle Linux VM as the + <literal>user1</literal> user. + </para> +<screen> +$ VBoxManage --nologo guestcontrol "My OL VM" run --exe "/bin/ls" \ +--username user1 --passwordfile pw.txt --wait-stdout -- -l /usr +</screen> + <para> + The <option>--exe</option> option specifies the absolute path of + the command to run in the guest VM, <filename>/bin/ls</filename>. + Use the <option>--</option> option to pass any arguments that + follow it to the <command>ls</command> command. + </para> + <para> + Use the <option>--username</option> option to specify the user + name, <literal>user1</literal> and use the + <option>--passwordfile</option> option to specify the name of a + file that includes the password for the <literal>user1</literal> + user, <filename>pw.txt</filename>. + </para> + <para> + The <option>--wait-stdout</option> option waits for the + <command>ls</command> guest process to complete before providing + the exit code and the command output. The + <option>--nologo</option> option suppresses the output of the logo + information. + </para> + <para> + The following <command>VBoxManage guestcontrol run</command> + command executes the <command>ipconfig</command> command on the + <literal>My Win VM</literal> Windows VM as the + <literal>user1</literal> user. Standard input, standard output, + and standard error are redirected from the VM to the host system + until the program completes. + </para> +<screen> +$ VBoxManage --nologo guestcontrol "My Win VM" run \ +--exe "c:\\windows\\system32\\ipconfig.exe" \ +--username user1 --passwordfile pw.txt --wait-stdout +</screen> + <para> + The <option>--exe</option> specifies the absolute path of command + to run in the guest VM, + <filename>c:\windows\system32\ipconfig.exe</filename>. The double + backslashes shown in this example are required only on UNIX host + systems. + </para> + <para> + Use the <option>--username</option> option to specify the user + name, <literal>user1</literal> and use the + <option>--passwordfile</option> option to specify the name of a + file that includes the password for the <literal>user1</literal> + user, <filename>pw.txt</filename>. + </para> + <para> + The <option>--wait-stdout</option> option waits for the + <command>ls</command> guest process to complete before providing + the exit code and the command output. The + <option>--nologo</option> option to suppress the output of the + logo information. + </para> + <para> + The following <command>VBoxManage guestcontrol start</command> + command executes the <command>ls -l /usr</command> command on the + <literal>My OL VM</literal> Oracle Linux VM until the program + completes. + </para> +<screen> +$ VBoxManage --nologo guestcontrol "My Win VM" start \ +--exe "c:\\windows\\system32\\ipconfig.exe" \ +--username user1 --passwordfile pw.txt +</screen> + <para> + The following <command>VBoxManage guestcontrol run</command> + command executes a <command>/usr/bin/busybox -l /usr</command> + command on the <literal>My OL VM</literal> Oracle Linux VM as the + <literal>user1</literal> user, explicitly using <literal>ls</literal> + as argument 0. + </para> +<screen> +$ VBoxManage --nologo guestcontrol "My OL VM" run --exe "/usr/bin/busybox" \ +--username user1 --passwordfile pw.txt --wait-stdout --arg0 ls -- -l /usr +</screen> + <para> + The <option>--exe</option> option specifies the absolute path of + the command to run in the guest VM, <filename>/usr/bin/busybox</filename>. + Use the <option>--</option> option to pass any arguments that + follow it to the <command>busybox</command> command. + </para> + <para> + Use the <option>--username</option> option to specify the user + name, <literal>user1</literal> and use the + <option>--passwordfile</option> option to specify the name of a + file that includes the password for the <literal>user1</literal> + user, <filename>pw.txt</filename>. + </para> + <para> + The <option>--wait-stdout</option> option waits for the + <command>ls</command> guest process to complete before providing + the exit code and the command output. The + <option>--nologo</option> option suppresses the output of the logo + information. + </para> + <para> + The <option>--arg0</option> option explicitly specifies the argument 0 + to use for the command to execute. + </para> + <note> + <para>If this option is not set, argument 0 will be taken from + the value of <option>--exe</option>, or, if + <option>--exe</option> is also not set, the first value + passed after <option>--</option>.</para> + <para>Use <option>--verbose</option> to see the effective + command line passed to the guest.</para> + </note> + <para> + The default behavior of argument 0 is to either use + the value from <option>--exe</option>, or, if not set, the first + value passed after <option>--</option>. + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-guestproperty.xml b/doc/manual/en_US/man_VBoxManage-guestproperty.xml new file mode 100644 index 00000000..8c264bae --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-guestproperty.xml @@ -0,0 +1,359 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage guestproperty +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-guestproperty" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage guestproperty</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-guestproperty</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-guestproperty</refname> + <refpurpose>manage virtual machine guest properties</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <cmdsynopsis id="synopsis-vboxmanage-guestproperty-get"> + <command>VBoxManage guestproperty get</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="req"><replaceable>property-name</replaceable></arg> + <arg>--verbose</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestproperty-enumerate"> + <command>VBoxManage guestproperty enumerate</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--no-timestamp</arg> + <arg>--no-flags</arg> + <arg>--relative</arg> + <arg>--old-format</arg> + <arg rep="repeat"><replaceable>patterns</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestproperty-set"> + <command>VBoxManage guestproperty set</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="req"><replaceable>property-name</replaceable></arg> + <arg><replaceable>property-value</replaceable><arg>--flags=<replaceable>flags</replaceable></arg></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestproperty-unset"> + <command>VBoxManage guestproperty unset</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="req"><replaceable>property-name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestproperty-wait"> + <command>VBoxManage guestproperty wait</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="req"><replaceable>patterns</replaceable></arg> + <arg>--timeout=<replaceable>msec</replaceable></arg> + <arg>--fail-on-timeout</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage guestproperty</command> command enables + you to set or retrieve the properties of a running virtual machine + (VM). See <xref linkend="guestadd-guestprops" />. Guest properties + are arbitrary name-value string pairs that can be written to and + read from by either the guest or the host. As a result, these + properties can be used as a low-volume communication channel for + strings provided that a guest is running and has the Guest + Additions installed. In addition, the Guest Additions + automatically set and maintain values whose keywords begin with + <literal>/VirtualBox/</literal>. + </para> + <refsect2> + <title>General Command Operand</title> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or name + of the VM. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestproperty-enumerate"> + <title>List All Properties for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + <!-- @todo the help output doesn't correctly insert a space after the /command tag if it comes last on a line... --> + The <command>VBoxManage guestproperty enumerate</command> command + lists each guest property and value for the specified + VM. Note that the output is limited if the guest's service is + not updating the properties, for example because the VM is not + running or because the Guest Additions are not installed. + </para> + <variablelist> + <varlistentry> + <term><option>--relative</option></term> + <listitem><para>Display the timestamp relative to current time.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--no-timestamp</option></term> + <listitem><para>Do not display the timestamp of the last update.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--no-flags</option></term> + <listitem><para>Do not display the flags.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--old-format</option></term> + <listitem><para>Use the output format from VirtualBox 6.1 and earlier.</para></listitem> + </varlistentry> + <varlistentry> + <term><option><replaceable>pattern</replaceable></option></term> + <listitem><para> + Filters the list of properties based on the specified + pattern, which can contain the following wildcard + characters: + </para><variablelist> + <varlistentry> + <term><literal>*</literal> (asterisk)</term> + <listitem><para> + Represents any number of characters. For example, + the <literal>/VirtualBox*</literal> pattern matches + all properties that begin with + <literal>/VirtualBox</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>?</literal> (question mark)</term> + <listitem><para> + Represents a single arbitrary character. For + example, the <literal>fo?</literal> pattern matches + both <literal>foo</literal> and + <literal>for</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>|</literal> (pipe)</term> + <listitem><para> + Specifies multiple alternative patterns. For + example, the <literal>s*|t*</literal> pattern + matches any property that begins with + <literal>s</literal> or <literal>t</literal>. + </para></listitem> + </varlistentry> + </variablelist></listitem> + </varlistentry> + + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestproperty-get"> + <title>Retrieve a Property Value for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestproperty get</command> command + retrieves the value of the specified property. If the property + cannot be found, for example because the guest is not running, + the command issues the following message: + </para> +<screen>No value set!</screen> + <variablelist> + <varlistentry> + <term><replaceable>property-name</replaceable></term> + <listitem><para> + Specifies the name of the property. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--verbose</option></term> + <listitem><para> + Provides the property value, timestamp, and any specified + value attributes. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestproperty-set"> + <title>Set a Property Value for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestproperty set</command> command + enables you to set a guest property by specifying the property + and its value. If you omit the value, the property is deleted. + </para> + <variablelist> + <varlistentry> + <term><replaceable>property-name</replaceable></term> + <listitem><para> + Specifies the name of the property. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>property-value</replaceable></term> + <listitem><para> + Specifies the value of the property. If no value is + specified, any existing value is removed. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--flags=<replaceable>flags</replaceable></option></term> + <listitem><para> + Specify the additional attributes of the value. The + following attributes can be specified as a comma-separated + list: + </para><variablelist> + <varlistentry> + <term><literal>TRANSIENT</literal></term> + <listitem><para> + Removes the value with the VM data when the VM + exits. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>TRANSRESET</literal></term> + <listitem><para> + Removes the value when the VM restarts or exits. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>RDONLYGUEST</literal></term> + <listitem><para> + Specifies that the value can be changed only by the + host and that the guest can read the value. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>RDONLYHOST</literal></term> + <listitem><para> + Specifies that the value can be changed only by the + guest and that the host can read the value. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>READONLY</literal></term> + <listitem><para> + Specifies that the value cannot be changed. + </para></listitem> + </varlistentry> + </variablelist></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestproperty-wait"> + <title>Wait for a Property Value to Be Created, Deleted, or Changed</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestproperty wait</command> command + waits for a particular value that is described by the pattern + string to change, to be deleted, or to be created. + </para> + <variablelist> + <varlistentry> + <term><replaceable>patterns</replaceable></term> + <listitem><para> + Specifies a pattern that matches the properties on which + you want to wait. For information about the pattern + wildcards, see the description of the + <option>--patterns</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--timeout<replaceable>msec</replaceable></option></term> + <listitem><para> + Specifies the number of microseconds to wait. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--fail-on-timeout</option></term> + <listitem><para> + Specifies that the command fails if the timeout is + reached. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestproperty-unset"> + <title>Unset a Virtual Machine Property Value</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestproperty unset</command> command + unsets the value of a guest property. + </para> + <para> + The alternate form of this subcommand is + <command>delete</command>. + </para> + <variablelist> + <varlistentry> + <term><replaceable>property-name</replaceable></term> + <listitem><para> + Specifies the name of the property. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command lists the guest properties and their values + for the <literal>win8</literal> VM. + </para> +<screen>$ VBoxManage guestproperty enumerate win8</screen> + <para> + The following command creates a guest property called + <literal>region</literal> for the <literal>win8</literal> VM. The + value of the property is set to <literal>west</literal>. + </para> +<screen>$ VBoxManage guestproperty set win8 region west</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-hostonlyif.xml b/doc/manual/en_US/man_VBoxManage-hostonlyif.xml new file mode 100644 index 00000000..f2bf8c0e --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-hostonlyif.xml @@ -0,0 +1,201 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage hostonlyif +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-hostonlyif" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage hostonlyif</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-hostonlyif</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-hostonlyif</refname> + <refpurpose>manage host-only network interfaces</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <cmdsynopsis id="synopsis-vboxmanage-hostonlyif-ipconfig"> + <command>VBoxManage hostonlyif ipconfig</command> + <arg choice="req"><replaceable>ifname</replaceable></arg> + <group> + <arg choice="plain">--dhcp</arg> + <arg choice="plain">--ip=<replaceable>IPv4-address</replaceable> <arg>--netmask=<replaceable>IPv4-netmask</replaceable></arg></arg> + <arg choice="plain">--ipv6=<replaceable>IPv6-address</replaceable> <arg>--netmasklengthv6=<replaceable>length</replaceable></arg></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-hostonlyif-create"> + <command>VBoxManage hostonlyif create</command> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-hostonlyif-remove"> + <command>VBoxManage hostonlyif remove</command> + <arg choice="req"><replaceable>ifname</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage hostonlyif</command> command enables you + to change the IP configuration of a host-only network interface. + For a description of host-only networking, see + <xref linkend="network_hostonly" />. Each host-only network + interface is identified by a name and can either use the internal + DHCP server or a manual IP configuration, both IPv4 and IPv6. + </para> + <refsect2 id="vboxmanage-hostonlyif-ipconfig"> + <title>Configure a Host-Only Interface</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage hostonlyif ipconfig</command> command + configures a host-only interface. + </para> + <variablelist> + <varlistentry> + <term><replaceable>ifname</replaceable></term> + <listitem><para> + Specifies the name of the network interface. The name is + of the form + <literal>vboxnet</literal><replaceable>N</replaceable> + where <replaceable>N</replaceable> is the interface + instance. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dhcp</option></term> + <listitem><para> + Uses DHCP for the network interface. + </para><para> + You cannot use this option with the <option>--ip</option>, + <option>--ipv6</option>, <option>--netmask</option>, and + <option>--netmasklengthv6</option> options. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ip=<replaceable>IPv4-address</replaceable></option></term> + <listitem><para> + Specifies the IPv4 IP address for the network interface. + </para><para> + You cannot use this option with the + <option>--dhcp</option>, <option>--ipv6</option>, and + <option>--netmasklengthv6</option> options. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--netmask=<replaceable>IPv4-netmask</replaceable></option></term> + <listitem><para> + Specifies the IPv4 netmask of the network interface. The + default value is <literal>255.255.255.0</literal>. + </para><para> + You can use this option only with the + <option>--ip</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ipv6=<replaceable>IPv6-address</replaceable></option></term> + <listitem><para> + Specifies the IPv6 IP address for the network interface. + </para><para> + You cannot use this option with the + <option>--dhcp</option>, <option>--ip</option>, and + <option>--netmask</option> options. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--netmasklengthv6=<replaceable>length</replaceable></option></term> + <listitem><para> + Specifies the length of the IPv6 network interface. The + default value is <literal>64</literal>. + </para><para> + You can use this option only with the + <option>--ipv6</option> option. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-hostonlyif-create"> + <title>Create a Network Interface on the Host System</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage hostonlyif create</command> command + creates a new host-only network interface on the host operating + system (OS). The network interface name is of the form + <literal>vboxnet</literal><replaceable>N</replaceable> where + <replaceable>N</replaceable> is the interface instance. You must + run this command before you can attach virtual machines (VMs) to + the host-only network. + </para> + </refsect2> + <refsect2 id="vboxmanage-hostonlyif-remove"> + <title>Remove a Network Interface From the Host System</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage hostonlyif remove</command> command + removes the specified host-only network interface from the host + OS. + </para> + <variablelist> + <varlistentry> + <term><replaceable>ifname</replaceable></term> + <listitem><para> + Specifies the name of the network interface. The name is + of the form + <literal>vboxnet</literal><replaceable>N</replaceable> + where <replaceable>N</replaceable> is the interface + instance. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command creates a new host-only network interface. + </para> +<screen>$ VBoxManage hostonlyif create +0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100% +Interface 'vboxnet2' was successfully created</screen> + <para> + The following command configures the IPv4 address for the + <literal>vboxnet2</literal> host-only network interface. + </para> +<screen>$ VBoxManage hostonlyif ipconfig vboxnet2 --ip 10.0.2.18</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-hostonlynet.xml b/doc/manual/en_US/man_VBoxManage-hostonlynet.xml new file mode 100644 index 00000000..14a98bb9 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-hostonlynet.xml @@ -0,0 +1,163 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage hostonlynet +--> +<!-- + Copyright (C) 2021-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-hostonlynet" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage hostonlynet</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-hostonlynet</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-hostonlynet</refname> + <refpurpose>Host Only Network management</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-hostonlynet-add"> + <command>VBoxManage hostonlynet add</command> + <arg choice="req">--name=<replaceable>netname</replaceable></arg> + <arg choice="opt">--id=<replaceable>netid</replaceable></arg> + <arg choice="req">--netmask=<replaceable>mask</replaceable></arg> + <arg choice="req">--lower-ip=<replaceable>address</replaceable></arg> + <arg choice="req">--upper-ip=<replaceable>address</replaceable></arg> + <group choice="opt"> + <arg choice="plain">--enable</arg> + <arg choice="plain">--disable</arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-hostonlynet-modify"> + <command>VBoxManage hostonlynet modify</command> + <group choice="req"> + <arg choice="plain">--name=<replaceable>netname</replaceable></arg> + <arg choice="plain">--id=<replaceable>netid</replaceable></arg> + </group> + <arg choice="opt">--lower-ip=<replaceable>address</replaceable></arg> + <arg choice="opt">--upper-ip=<replaceable>address</replaceable></arg> + <arg choice="opt">--netmask=<replaceable>mask</replaceable></arg> + <group choice="opt"> + <arg choice="plain">--enable</arg> + <arg choice="plain">--disable</arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-hostonlynet-remove"> + <command>VBoxManage hostonlynet remove</command> + <group choice="req"> + <arg choice="plain">--name=<replaceable>netname</replaceable></arg> + <arg choice="plain">--id=<replaceable>netid</replaceable></arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + The <command>hostonlynet</command> commands enable you to control + host-only networks. + </para> + + <refsect2 id="vboxmanage-hostonlynet-common-options"> + <title>Common options</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>The subcommands of <command>hostonlynet</command> all operate on an + host-only network that can be identified via its name or uuid:</para> + <variablelist> + <varlistentry> + <term>--name=<replaceable>netname</replaceable></term> + <listitem><para>The host-only network name. You see it as + VBoxNetworkName in the output from + <command>VBoxManage list hostonlynets</command>. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--id=<replaceable>netid</replaceable></term> + <listitem><para>The host-only network uuid. If not specified when + adding a new network, one will be generated automatically. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-hostonlynet-add"> + <title>hostonlynet add</title> + <remark role="help-copy-synopsis"/> + <para> + Adds a new host-only network. + </para> + <para> + Options configuring the host-only network: + </para> + <variablelist> + <varlistentry> + <term><option>--netmask=<replaceable>mask</replaceable></option></term> + <listitem><para>The network mask. Typically 255.255.255.0.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--lower-ip=<replaceable>address</replaceable></option>, <option>--upper-ip=<replaceable>address</replaceable></option></term> + <listitem><para>The IP address range for handing out via DHCP. The upper + boundrary is inclusive while the lower one is not, so the upper address + will be handed out to a client, while the lower + address will be used by the host itself.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--enable</option>, --disable</term> + <listitem><para>Whether to enable the host-only network or disable it. If not specified, + the network will be created in enabled state.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-hostonlynet-modify"> + <title>hostonlynet modify</title> + <remark role="help-copy-synopsis"/> + <para> + This modifies an existing host-only network configuration. It takes the same + options as the <command>add</command> command. + </para> + </refsect2> + + <refsect2 id="vboxmanage-hostonlynet-remove"> + <title>hostonlynet remove</title> + <remark role="help-copy-synopsis"/> + <para> + Removes the specified host-only network. + </para> + </refsect2> + + </refsect1> + +</refentry> + diff --git a/doc/manual/en_US/man_VBoxManage-import.xml b/doc/manual/en_US/man_VBoxManage-import.xml new file mode 100644 index 00000000..8e2ba748 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-import.xml @@ -0,0 +1,461 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage import +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-import" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage import</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-import</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-import</refname> + <refpurpose>import a virtual appliance in OVF format or from a cloud service and create virtual machines</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-import-ovf"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage import</command> + <group choice="req"> + <arg choice="plain"><replaceable>ovfname</replaceable></arg> + <arg choice="plain"><replaceable>ovaname</replaceable></arg> + </group> + <arg>--dry-run</arg> + <arg>--options=<group choice="plain"> + <arg choice="plain">keepallmacs</arg> + <arg choice="plain">keepnatmacs</arg> + <arg choice="plain">importtovdi</arg> + </group></arg> + <arg>--vsys=<replaceable>n</replaceable></arg> + <arg>--ostype=<replaceable>ostype</replaceable></arg> + <arg>--vmname=<replaceable>name</replaceable></arg> + <arg>--settingsfile=<replaceable>file</replaceable></arg> + <arg>--basefolder=<replaceable>folder</replaceable></arg> + <arg>--group=<replaceable>group</replaceable></arg> + <arg>--memory=<replaceable>MB</replaceable></arg> + <arg>--cpus=<replaceable>n</replaceable></arg> + <arg>--description=<replaceable>text</replaceable></arg> + <arg>--eula=<group choice="plain"> + <arg choice="plain">show</arg> + <arg choice="plain">accept</arg> + </group></arg> + <arg>--unit=<replaceable>n</replaceable></arg> + <arg>--ignore</arg> + <arg>--scsitype=<group choice="plain"> + <arg choice="plain">BusLogic</arg> + <arg choice="plain">LsiLogic</arg> + </group></arg> + <!-- <arg>--controller=<replaceable>n</replaceable></arg> --> + <arg>--disk=<replaceable>path</replaceable></arg> + <arg>--controller=<replaceable>index</replaceable></arg> + <arg>--port=<replaceable>n</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-import-cloud"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage import</command> + <arg choice="plain">OCI://</arg> + <arg choice="plain">--cloud</arg> + <arg>--ostype=<replaceable>ostype</replaceable></arg> + <arg>--vmname=<replaceable>name</replaceable></arg> + <arg>--basefolder=<replaceable>folder</replaceable></arg> + <arg>--memory=<replaceable>MB</replaceable></arg> + <arg>--cpus=<replaceable>n</replaceable></arg> + <arg>--description=<replaceable>text</replaceable></arg> + <arg choice="req">--cloudprofile=<replaceable>profile</replaceable></arg> + <arg choice="req">--cloudinstanceid=<replaceable>id</replaceable></arg> + <arg>--cloudbucket=<replaceable>bucket</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage import</command> command imports a virtual + appliance either in OVF format or from a cloud service such as &oci;. + The import is performed by copying virtual disk images (by default using + the VMDK image format) and by creating virtual machines (VMs) in + &product-name;. See <xref linkend="ovf" />. + </para> + <para> + You must specify the path name of an OVF file or OVA archive to + use as input, or a placeholder for the cloud case. For OVF appliances + ensure that any disk images are in the same directory as the OVF file. + </para> + <para> + Note that any options you specify to control the imported virtual + appliance or to modify the import parameters rely on the contents + of the OVF file or the information from the cloud service. + </para> + <para> + Before you use the import operation to create the VM, perform a + dry run to verify the correctness of your configuration. This is more + useful with an OVF or OVA appliance, because with a cloud service even + a dry run needs to perform most of the time consuming steps. + </para> + <para> + The import from a cloud service downloads a temporary file containing + both the boot image and some metadata describing the details of the + VM instance. The temporary file is deleted after successful import. + </para> + <refsect2> + <title>Common Options</title> + <variablelist> + <varlistentry> + <term><replaceable>ovfname</replaceable> | <replaceable>ovaname</replaceable></term> + <listitem><para> + Specifies the name of the OVF file or OVA archive that + describes the appliance. In the cloud case this is usually + a fixed string such as <literal>OCI://</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dry-run</option></term> + <!-- Does this option really work for cloud import? --> + <listitem><para> + Performs a dry run of the <command>VBoxManage + import</command> command before you perform the actual + import operation. A dry run operation does the following: + </para><itemizedlist> + <listitem><para> + Outputs a description of the appliance's contents + based on the specified OVF or OVA file. + </para></listitem> + <listitem><para> + Shows how the appliance would be imported into + &product-name;. In addition, the output shows any + options that you can use to change the import + behavior. + </para></listitem> + </itemizedlist><para> + The shortened form of this option is <option>-n</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--options=keepallmacs | keepnatmacs | importtovdi</option></term> + <!-- Does this option really work for cloud import? --> + <listitem><para> + Enables you to fine tune the import operation. + </para><para> + Valid arguments are as follows: + </para><itemizedlist> + <listitem><para> + <literal>keepallmacs</literal>: Specifies that the MAC + addresses of every virtual network card are left + unchanged. + </para></listitem> + <listitem><para> + <literal>keepnatmacs</literal>: Specifies that the MAC + addresses of every virtual network card are left + unchanged if the network type is NAT. + </para></listitem> + <listitem><para> + <literal>importtovdi</literal>: Specifies that all new + disk images are in VDI file format. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--ostype=<replaceable>ostype</replaceable></option></term> + <listitem><para> + Specifies the guest operating system (OS) information for + the VM. Use the <command>VBoxManage list ostypes</command> + command to view the OS type identifiers. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vmname=<replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the name of the VM to be used by &product-name;. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--basefolder=<replaceable>folder</replaceable></option></term> + <!-- Does this option really work for cloud import? --> + <listitem><para> + Specifies the folder where the files of the imported VM + are stored. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--memory=<replaceable>MB</replaceable></option></term> + <listitem><para> + Specifies the memory size in Megabytes for the imported VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpus=<replaceable>n</replaceable></option></term> + <listitem><para> + Specifies the number of CPUs for the imported VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--description=<replaceable>text</replaceable></option></term> + <listitem><para> + Specifies the description text visible in the GUI and + CLI when checking the VM details. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-import-ovf"> + <title>OVF / OVA Import Options</title> + <para> + The following options are specific for importing a virtual appliance + in OVF or OVA format. Such an appliance can contain one or more VMs, + which requires specifying which VM configuration should be adjusted + in case you want to change it. See <xref linkend="ovf-import-appliance" />. + </para> + <remark role="help-copy-synopsis"/> + <variablelist> + <varlistentry> + <term><option>--vsys=<replaceable>n</replaceable></option></term> + <listitem><para> + Specifies the index selecting a specific VM within the + appliance. Affects the following options. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unit=<replaceable>n</replaceable></option></term> + <listitem><para> + Specifies the index selecting a specific unit of a VM + within the appliance. Affects the following options. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--settingsfile=<replaceable>file</replaceable></option></term> + <listitem><para> + Specifies the name (with or without path) of the VM config + file which will be created as part of the import. Usually + the preferred way is overriding the VM name with + <option>--vmname</option> and if necessary specify the + folder in which to create the VM with + <option>--basefolder</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--group=<replaceable>group</replaceable></option></term> + <listitem><para> + Specifies the primary group of the imported VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--eula=show | accept</option></term> + <listitem><para> + Enables you to show or accept the license conditions of a + VM within the appliance, + </para><para> + Valid arguments are as follows: + </para><itemizedlist> + <listitem><para> + <literal>show</literal>: Shows the EULA of a VM. + </para></listitem> + <listitem><para> + <literal>accepts</literal>: Accepts the EULA of a VM. + Any VMs in an appliance which have an EULA require + accepting it, otherwise the import will fail. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--ignore</option></term> + <listitem><para> + Ignores the current unit of an imported VM, effectively + removing the associated hardware. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--scsitype=BusLogic | LsiLogic</option></term> + <listitem><para> + Enables you to select the type of the SCSI controller for + the current unit of an imported VM. + </para><para> + Valid arguments are as follows: + </para><itemizedlist> + <listitem><para> + <literal>BusLogic</literal>: Uses the (very old) BusLogic + SCSI controller type. + </para></listitem> + <listitem><para> + <literal>LsiLogic</literal>: Uses the (more modern) + LsiLogic SCSI controller type. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-import-cloud"> + <title>Cloud Import Options</title> + <para> + The following options are specific for importing a VM instance + from a cloud service provider. It always deals with a single VM. + See <xref linkend="cloud-import-oci" />. + </para> + <remark role="help-copy-synopsis"/> + <variablelist> + <varlistentry> + <term><option>--cloud</option></term> + <listitem><para> + Specifies that the import should be from the cloud. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudprofile=<replaceable>profile</replaceable></option></term> + <listitem><para> + Specifies the cloud profile which is used to connect to the + cloud service provider. The cloud profile contains your &oci; + account details, such as your user OCID and the fingerprint + for your public key. To use a cloud profile, you must have + the required permissions on &oci;. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudinstanceid=<replaceable>id</replaceable></option></term> + <listitem><para> + Specifies the ID of an existing instance in the cloud. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudbucket=<replaceable>bucket</replaceable></option></term> + <listitem><para> + Specifies the bucket name in which to store the object created + from the instance. In &oci;, a bucket is a logical container + for storing objects. By default the first bucket available with + the cloud profile is used. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following example performs the dry run of an OVF import operation + for a sample appliance that contains a Windows 10 guest: + </para> +<screen>$ VBoxManage import Windows10.ovf --dry-run +Interpreting Windows10.ovf... +OK. +Virtual system 0: + 0: Suggested OS type: "Windows10_64" + (change with "--vsys 0 --ostype <type>"; use "list ostypes" to list all) + 1: Suggested VM name "win10-appliance" + (change with "--vsys 0 --vmname <name>") + 2: Suggested VM group "/" + (change with "--vsys 0 --group <group>") + 3: Suggested VM settings file name "/home/user1/VirtualBox VMs/win10-appliance/win10-appliance.vbox" + (change with "--vsys 0 --settingsfile <filename>") + 4: Suggested VM base folder "/home/user1/VirtualBox VMs" + (change with "--vsys 0 --basefolder <path>") + 5: End-user license agreement + (display with "--vsys 0 --eula show"; + accept with "--vsys 0 --eula accept") + 6: Number of CPUs: 1 + (change with "--vsys 0 --cpus <n>") + 7: Guest memory: 2048 MB (change with "--vsys 0 --memory <MB>") + 8: Sound card (appliance expects "ensoniq1371", can change on import) + (disable with "--vsys 0 --unit 8 --ignore") + 9: USB controller + (disable with "--vsys 0 --unit 9 --ignore") +10: Network adapter: orig bridged, config 2, extra type=bridged +11: Floppy + (disable with "--vsys 0 --unit 11 --ignore") +12: SCSI controller, type BusLogic + (change with "--vsys 0 --unit 12 --scsitype {BusLogic|LsiLogic}"; + disable with "--vsys 0 --unit 12 --ignore") +13: IDE controller, type PIIX4 + (disable with "--vsys 0 --unit 13 --ignore") +14: Hard disk image: source image=Windows10.vmdk, + target path=/home/user1/disks/Windows10.vmdk, controller=12;channel=0 + (change target path with "--vsys 0 --unit 14 --disk <path>"; + change controller with "--vsys 0 --unit 14 --controller <index>"; + change controller port with "--vsys 0 --unit 14 --port <n>"; + disable with "--vsys 0 --unit 14 --ignore")</screen> + <para> + The dry run output lists and numbers the individual configuration + items that are described in the <filename>Windows10.ovf</filename> + file. Some of the items include information about how to disable + or change the configuration of the item. + </para> + <para> + You can disable many of the items by using the <option>--vsys + <replaceable>X</replaceable> --unit <replaceable>Y</replaceable> + --ignore</option> options. <replaceable>X</replaceable> is the + number of the virtual system. The value is <literal>0</literal> + unless the appliance includes several virtual system descriptions. + <replaceable>Y</replaceable> is the configuration item number. + </para> + <para> + Item 1 in the example command output specifies the name of the + target machine. Items 12 and 13 specify the IDE and SCSI hard disk + controllers, respectively. + </para> + <para> + Item 14 indicates the hard disk image and the + <option>--disk</option> option specifies the target path where the + image will be stored, the <option>--controller</option> option specifies + which controller the disk will be attached to, and the + <option>--port</option> option specifies which port on the controller the + disk will be attached to. The default values are specified in the OVF file. + </para> + <para> + You can combine several items for the same virtual system by + specifying the same value for the <option>--vsys</option> option. + For example use the following command to import a machine as + described in the OVF, exclude the sound card and USB controller + and specify that the disk image is stored with a different name. + </para> +<screen>$ VBoxManage import Windows10.ovf --vsys 0 --unit 8 --ignore \ + --unit 9 --ignore --unit 14 --disk Windows10_disk0.vmdk</screen> + <para> + The following example illustrates how to import a VM from &oci;. To find + the &oci; VM instances and its ID you can list all available instances + with: + </para> +<screen>$ VBoxManage cloud --provider=OCI --profile=<replaceable>cloud-profile-name</replaceable> list instances</screen> + <para> + Once you know the ID the following command imports the instance from + &oci;: + </para> +<screen>$ VBoxManage import OCI:// --cloud --vmname OCI_FreeBSD_VM --memory 4000 \ + --cpus 3 --ostype FreeBSD_64 --cloudprofile "standard user" \ + --cloudinstanceid ocid1.instance.oc1.iad.abuwc... --cloudbucket myBucket</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-list.xml b/doc/manual/en_US/man_VBoxManage-list.xml new file mode 100644 index 00000000..0347a76e --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-list.xml @@ -0,0 +1,526 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage list +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-list" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage list</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-list</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-list</refname> + <refpurpose>view system information and VM configuration details</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-list"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage list</command> + <arg>--long</arg> + <arg>--sorted</arg> + <group> + <arg choice="plain">bridgedifs</arg> + <arg choice="plain">cloudnets</arg> + <arg choice="plain">cloudprofiles</arg> + <arg choice="plain">cloudproviders</arg> + <arg choice="plain">cpu-profiles</arg> + <arg choice="plain">dhcpservers</arg> + <arg choice="plain">dvds</arg> + <arg choice="plain">extpacks</arg> + <arg choice="plain">floppies</arg> + <arg choice="plain">groups</arg> + <arg choice="plain">hddbackends</arg> + <arg choice="plain">hdds</arg> + <arg choice="plain">hostcpuids</arg> + <arg choice="plain">hostdrives</arg> + <arg choice="plain">hostdvds</arg> + <arg choice="plain">hostfloppies</arg> + <arg choice="plain">hostinfo</arg> + <arg choice="plain">hostonlyifs</arg> + <arg choice="plain">hostonlynets</arg> + <arg choice="plain">intnets</arg> + <arg choice="plain">natnets</arg> + <arg choice="plain">ostypes</arg> + <arg choice="plain">runningvms</arg> + <arg choice="plain">screenshotformats</arg> + <arg choice="plain">systemproperties</arg> + <arg choice="plain">usbfilters</arg> + <arg choice="plain">usbhost</arg> + <arg choice="plain">vms</arg> + <arg choice="plain">webcams</arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage list</command> subcommands enable you to + obtain information about the &product-name; software, the VMs + and associated services that you create. + </para> + <refsect2 id="vboxmanage-list-common-options"> + <title>Common Options</title> + <variablelist> + <varlistentry> + <term><option>--long</option></term> + <listitem><para> + Shows detailed information about each information entry + if available. The short form of this option is + <option>-l</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--sorted</option></term> + <listitem><para> + Sorts the list of information entries alphabetically. The + short form of this option is <option>-s</option>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-list-bridgedifs"> + <title>List the Bridged Network Interfaces on the Host System</title> + <cmdsynopsis id="synopsis-vboxmanage-list-bridgedifs"> + <command>VBoxManage list</command> + <arg choice="plain">bridgedifs</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list bridgedifs</command> command lists + the bridged network interfaces that are currently available on + the host system. The output shows detailed configuration + information about each interface. See <xref linkend="networkingdetails"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-cloudnets"> + <title>List the Cloud Network Interfaces</title> + <cmdsynopsis id="synopsis-vboxmanage-list-cloudnets"> + <command>VBoxManage list</command> + <arg choice="plain">cloudnets</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list cloudnets</command> command + lists the cloud network interfaces that have been configured. A cloud + network interface provides connectivity between local VMs and a + cloud network. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-cloudprofiles"> + <title>List the Cloud Profiles</title> + <cmdsynopsis id="synopsis-vboxmanage-list-cloudprofiles"> + <command>VBoxManage list</command> + <arg choice="plain">cloudprofiles</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list cloudprofiles</command> command + lists the cloud profiles that have been configured. A cloud + profile contains settings for a cloud service account. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-cloudproviders"> + <title>List the Cloud Providers</title> + <cmdsynopsis id="synopsis-vboxmanage-list-cloudproviders"> + <command>VBoxManage list</command> + <arg choice="plain">cloudproviders</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list cloudproviders</command> command + lists the cloud providers that are supported by &product-name;. + Oracle Cloud Infrastructure is an example of a cloud provider. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-cpu-profiles"> + <title>List the known CPU Profiles</title> + <cmdsynopsis id="synopsis-vboxmanage-list-cpu-profiles"> + <command>VBoxManage list</command> + <arg choice="plain">cpu-profiles</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list cpu-profiles</command> command + lists the CPU profiles that are known by &product-name;. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-dhcpservers"> + <title>List the DHCP Servers on the Host System</title> + <cmdsynopsis id="synopsis-vboxmanage-list-dhcpservers"> + <command>VBoxManage list</command> + <arg choice="plain">dhcpservers</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list dhcpservers</command> command lists + the DHCP servers that are currently available on the host + system. The output shows detailed configuration information + about each DHCP server. See <xref linkend="networkingdetails"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-dvds"> + <title>List the DVD Virtual Disk Images</title> + <cmdsynopsis id="synopsis-vboxmanage-list-dvds"> + <command>VBoxManage list</command> + <arg choice="plain">dvds</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list dvds</command> command shows + information about the DVD virtual disk images that are currently + in use by the &product-name; software. For each image, the + output shows all the settings, the UUIDs associated with the + image by &product-name;, and all files associated with the + image. + </para> + <para> + This command performs the same function as the Virtual Media + Manager. See <xref linkend="virtual-media-manager"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-extpacks"> + <title>List the Installed &product-name; Extension Packs</title> + <cmdsynopsis id="synopsis-vboxmanage-list-extpacks"> + <command>VBoxManage list</command> + <arg choice="plain">extpacks</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list extpacks</command> command shows + all &product-name; extension packs that are currently installed. + See <xref linkend="intro-installing"/> and + <xref linkend="vboxmanage-extpack"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-floppies"> + <title>List the Floppy Disk Virtual Disk Images</title> + <cmdsynopsis id="synopsis-vboxmanage-list-floppies"> + <command>VBoxManage list</command> + <arg choice="plain">floppies</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list floppies</command> command shows + information about the floppy disk images that are currently in + use by the &product-name; software. For each image, the output + shows all the settings, the UUIDs associated with the image by + &product-name;, and all files associated with the image. + </para> + <para> + This command performs the same function as the Virtual Media + Manager. See <xref linkend="virtual-media-manager"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-groups"> + <title>List the Virtual Machine Groups</title> + <cmdsynopsis id="synopsis-vboxmanage-list-groups"> + <command>VBoxManage list</command> + <arg choice="plain">groups</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list groups</command> command shows + all VM groups. See <xref linkend="gui-vmgroups"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hddbackends"> + <title>List the Virtual Disk Backends</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hddbackends"> + <command>VBoxManage list</command> + <arg choice="plain">hddbackends</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list hddbackends</command> command lists + all known virtual disk backends of the &product-name; software. + For each such format, such as VDI, VMDK, or RAW, this command + lists the backend's capabilities and configuration. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hdds"> + <title>List the Hard Disk Virtual Disk Images</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hdds"> + <command>VBoxManage list</command> + <arg choice="plain">hdds</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list hdds</command> command shows + information about the hard disk virtual disk images that are + currently in use by the &product-name; software. For each image, + the output shows all the settings, the UUIDs associated with the + image by &product-name;, and all files associated with the + image. + </para> + <para> + This command performs the same function as the Virtual Media + Manager. See <xref linkend="virtual-media-manager"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hostcpuids"> + <title>List the CPUID Information for the Host System CPUs</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hostcpuids"> + <command>VBoxManage list</command> + <arg choice="plain">hostcpuids</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list hostcpuids</command> command lists + CPUID information for each CPU on the host system. Use this + information to perform a more fine grained analyis of the host + system's virtualization capabilities. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hostdrives"> + <title>List the Storage Drives on the Host System</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hostdrives"> + <command>VBoxManage list</command> + <arg choice="plain">hostdrives</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list hostdrives</command> command lists + the disk drives on the host system potentially useful for creating + a VMDK raw disk image. Each entry includes the name used to + reference them from within &product-name;. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hostdvds"> + <title>List the DVD Drives on the Host System</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hostdvds"> + <command>VBoxManage list</command> + <arg choice="plain">hostdvds</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list hostdvds</command> command lists + the DVD drives on the host system. Each DVD entry includes + the name used to access them from within &product-name;. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hostfloppies"> + <title>List the Floppy Disk Drives on the Host System</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hostfloppies"> + <command>VBoxManage list</command> + <arg choice="plain">hostfloppies</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list hostfloppies</command> command + lists the floppy disk drives on the host system. Each floppy + disk entry includes the name used to access them from within + &product-name;. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hostinfo"> + <title>List Information About the Host System</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hostinfo"> + <command>VBoxManage list</command> + <arg choice="plain">hostinfo</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list hostinfo</command> command shows + information about the host system. The output includes + information about the CPUs, memory, and the OS version. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hostonlyifs"> + <title>List the Host-Only Network Interfaces on the Host System</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hostonlyifs"> + <command>VBoxManage list</command> + <arg choice="plain">hostonlyifs</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list hostonlyifs</command> command lists + the host-only network interfaces that are currently available on + the host system. The output shows detailed configuration + information about each interface. See <xref linkend="networkingdetails"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hostonlynets"> + <title>List Host-Only Networks</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hostonlynets"> + <command>VBoxManage list</command> + <arg choice="plain">hostonlynets</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list hostonlynets</command> command + lists the host-only networks that have been configured. A + host-only network provides connectivity between the host and + local VMs. See <xref linkend="networkingdetails"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-intnets"> + <title>List Internal Networks</title> + <cmdsynopsis id="synopsis-vboxmanage-list-intnets"> + <command>VBoxManage list</command> + <arg choice="plain">intnets</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list intnets</command> command shows + information about the internal networks. See + <xref linkend="networkingdetails"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-natnets"> + <title>List the NAT Network Interfaces on the Host System</title> + <cmdsynopsis id="synopsis-vboxmanage-list-natnets"> + <command>VBoxManage list</command> + <arg choice="plain">natnets</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list natnets</command> command lists the + NAT network interfaces that are currently available on the host + system. See <xref linkend="networkingdetails"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-ostypes"> + <title>List the Guest Operating Systems</title> + <cmdsynopsis id="synopsis-vboxmanage-list-ostypes"> + <command>VBoxManage list</command> + <arg choice="plain">ostypes</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list ostypes</command> command lists all + guest operating systems (OSes) that are known to &product-name;. + Each OS entry includes an identifier, a description, a family + identifier, a family description, and whether the OS has 64-bit + support. + </para> + <para> + You can use these identifiers with the <command>VBoxManage + modifyvm</command> command. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-runningvms"> + <title>List the Running Virtual Machines</title> + <cmdsynopsis id="synopsis-vboxmanage-list-runningvms"> + <command>VBoxManage list</command> + <arg choice="plain">runningvms</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list runningvms</command> command lists + all virtual machines (VMs) that are currently running. By + default this displays a compact list that shows the name and + UUID of each VM. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-screenshotformats"> + <title>List the Available Screen Shot Formats</title> + <cmdsynopsis id="synopsis-vboxmanage-list-screenshotformats"> + <command>VBoxManage list</command> + <arg choice="plain">screenshotformats</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list screenshotformats</command> command + shows the list of available screen shot formats. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-systemproperties"> + <title>List System Properties</title> + <cmdsynopsis id="synopsis-vboxmanage-list-systemproperties"> + <command>VBoxManage list</command> + <arg choice="plain">systemproperties</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list systemproperties</command> command + shows a large collection of global &product-name; settings and + limits, such as minimum and maximum guest RAM, virtual hard disk + size, folder settings, and the current authentication library in + use. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-usbfilters"> + <title>List the Registered Global USB Filters</title> + <cmdsynopsis id="synopsis-vboxmanage-list-usbfilters"> + <command>VBoxManage list</command> + <arg choice="plain">usbfilters</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list usbfilters</command> command lists + all global USB filters registered with &product-name; and + displays the filter parameters. Global USB filters are for + devices which are accessible to all virtual machines. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-usbhost"> + <title>List the USB Devices on the Host System</title> + <cmdsynopsis id="synopsis-vboxmanage-list-usbhost"> + <command>VBoxManage list</command> + <arg choice="plain">usbhost</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list usbhost</command> command shows + information about the USB devices that are attached to the host + system. The output includes information that you can use to + construct USB filters and indicates whether the device is + currently in use by the host system. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-vms"> + <title>List Virtual Machines</title> + <cmdsynopsis id="synopsis-vboxmanage-list-vms"> + <command>VBoxManage list</command> + <arg choice="plain">vms</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list vms</command> command lists all + virtual machines (VMs) that are currently registered with + &product-name;. By default this command displays a compact list + that shows the name and UUID of each VM. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-webcams"> + <title>List the Webcams Attached to a Running Virtual Machine</title> + <cmdsynopsis id="synopsis-vboxmanage-list-webcams"> + <command>VBoxManage list</command> + <arg choice="plain">webcams</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list webcams</command> command shows the + list of webcams that are attached to the running VM. + </para> + <para> + The output is a list of absolute paths or aliases that are used + to attach the webcams to the VM by using the <command>VBoxManage + webcam attach</command> command. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command lists the VM groups configured for + &product-name;. + </para> +<screen>$ VBoxManage list groups +"/Linux-VMs" +"/Windows-VMs"</screen> + <para> + The following command lists the VMs that are currently running. + </para> +<screen>$ VBoxManage list runningvms +"ol7" {<replaceable>ol7-UUID</replaceable>} +"win8" {<replaceable>win8-UUID</replaceable>}</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-mediumio.xml b/doc/manual/en_US/man_VBoxManage-mediumio.xml new file mode 100644 index 00000000..cb51f745 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-mediumio.xml @@ -0,0 +1,178 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage mediumio +--> +<!-- + Copyright (C) 2018-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-mediumio" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage mediumio</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-mediumio</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-mediumio</refname> + <refpurpose>medium content access</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-mediumio-formatfat"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage mediumio</command> + <group choice="req"> + <arg choice="plain">--disk=<replaceable>uuid|filename</replaceable></arg> + <arg choice="plain">--dvd=<replaceable>uuid|filename</replaceable></arg> + <arg choice="plain">--floppy=<replaceable>uuid|filename</replaceable></arg> + </group> + <arg>--password-file=<replaceable>-|filename</replaceable></arg> + <arg choice="plain">formatfat</arg> + <arg>--quick</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-mediumio-cat"> + <command>VBoxManage mediumio</command> + <group choice="req"> + <arg choice="plain">--disk=<replaceable>uuid|filename</replaceable></arg> + <arg choice="plain">--dvd=<replaceable>uuid|filename</replaceable></arg> + <arg choice="plain">--floppy=<replaceable>uuid|filename</replaceable></arg> + </group> + <arg>--password-file=<replaceable>-|filename</replaceable></arg> + <arg choice="plain">cat</arg> + <arg>--hex</arg> + <arg>--offset=<replaceable>byte-offset</replaceable></arg> + <arg>--size=<replaceable>bytes</replaceable></arg> + <arg>--output=<replaceable>-|filename</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-mediumio-stream"> + <command>VBoxManage mediumio</command> + <group choice="req"> + <arg choice="plain">--disk=<replaceable>uuid|filename</replaceable></arg> + <arg choice="plain">--dvd=<replaceable>uuid|filename</replaceable></arg> + <arg choice="plain">--floppy=<replaceable>uuid|filename</replaceable></arg> + </group> + <arg>--password-file=<replaceable>-|filename</replaceable></arg> + <arg choice="plain">stream</arg> + <arg>--format=<replaceable>image-format</replaceable></arg> + <arg>--variant=<replaceable>image-variant</replaceable></arg> + <arg>--output=<replaceable>-|filename</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <refsect2 id="vboxmanage-mediumio-common-options"> + <title>Common options</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>The subcommands of <command>mediumio</command> all operate on a medium which need to be specified, optionally + with an encryption password. The following common options can be placed before or after the sub-command:</para> + <variablelist> + <varlistentry> + <term>--disk=<replaceable>uuid|filename</replaceable></term> + <listitem><para>Either the UUID or filename of a harddisk image, e.g. VDI, VMDK, VHD, ++.</para></listitem> + </varlistentry> + <varlistentry> + <term>--dvd=<replaceable>uuid|filename</replaceable></term> + <listitem><para>Either the UUID or filename of a DVD image, e.g. ISO, DMG, CUE.</para></listitem> + </varlistentry> + <varlistentry> + <term>--floppy=<replaceable>uuid|filename</replaceable></term> + <listitem><para>Either the UUID or filename of a floppy image, e.g. IMG.</para></listitem> + </varlistentry> + <varlistentry> + <term>--password-file=<replaceable>-|filename</replaceable></term> + <listitem><para>The name of a file containing the medium encryption password. If <option>-</option> + is specified, the password will be read from stdin. </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-mediumio-formatfat"> + <title>mediumio formatfat</title> + <remark role="help-copy-synopsis"/> + <para> + Formats a floppy medium with the FAT file system. This will erase the + content of the medium. + </para> + <variablelist> + <varlistentry> + <term><option>--quick</option></term><listitem><para>Quickformat the medium.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-mediumio-cat"> + <title>mediumio cat</title> + <remark role="help-copy-synopsis"/> + <para> + Dumps the medium content to stdout or the specified file. + </para> + <variablelist> + <varlistentry> + <term><option>--hex</option></term><listitem><para>Dump as hex bytes.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--offset</option></term><listitem><para>The byte offset in the medium to start.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--size</option></term><listitem><para>The number of bytes to dump.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--output</option></term> + <listitem><para>The output filename. As usual <option>-</option> is take to mean stdout.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-mediumio-stream"> + <title>mediumio stream</title> + <remark role="help-copy-synopsis"/> + <para> + Converts the medium to a streamable format and dumps it to the given output. + </para> + <variablelist> + <varlistentry> + <term><option>--format</option></term><listitem><para>The format of the destination image.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--variant</option></term><listitem><para>The medium variant for the destination.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--output</option></term> + <listitem><para>The output filename. As usual <option>-</option> is take to mean stdout.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsect1> + +</refentry> + diff --git a/doc/manual/en_US/man_VBoxManage-mediumproperty.xml b/doc/manual/en_US/man_VBoxManage-mediumproperty.xml new file mode 100644 index 00000000..7526db53 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-mediumproperty.xml @@ -0,0 +1,220 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage mediumproperty +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-mediumproperty" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage mediumproperty</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-mediumproperty</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-mediumproperty</refname> + <refpurpose>manage medium properties</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-mediumproperty-set"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage mediumproperty</command> + <group> + <arg choice="plain">disk</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">floppy</arg> + </group> + <arg choice="plain">set</arg> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>filename</replaceable></arg> + </group> + <arg choice="req"><replaceable>property-name</replaceable></arg> + <arg choice="req"><replaceable>property-value</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-mediumproperty-get"> + <command>VBoxManage mediumproperty</command> + <group> + <arg choice="plain">disk</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">floppy</arg> + </group> + <arg choice="plain">get</arg> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>filename</replaceable></arg> + </group> + <arg choice="req"><replaceable>property-name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-mediumproperty-delete"> + <command>VBoxManage mediumproperty</command> + <group> + <arg choice="plain">disk</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">floppy</arg> + </group> + <arg choice="plain">delete</arg> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>filename</replaceable></arg> + </group> + <arg choice="req"><replaceable>property-name</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage mediumproperty</command> command enables + you to set, retrieve, or delete a medium property. + </para> + <refsect2 id="vboxmanage-mediumproperty-set"> + <title>Set a Medium Property</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage mediumproperty set</command> command + enables you to set a medium property. + </para> + <variablelist> + <varlistentry> + <term><literal>disk | dvd | floppy</literal></term> + <listitem><para> + Specifies the type of medium. Valid values are + <literal>disk</literal> (hard drive), + <literal>dvd</literal>, or <literal>floppy</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>filename</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or + absolute path name of the medium or image. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>property-name</replaceable></term> + <listitem><para> + Specifies the name of the property. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>property-value</replaceable></term> + <listitem><para> + Specifies the value of the specified property. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-mediumproperty-get"> + <title>Retrieve a Medium Property Value</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage mediumproperty get</command> command + enables you to retrieve the value of a medium property. + </para> + <variablelist> + <varlistentry> + <term><literal>disk | dvd | floppy</literal></term> + <listitem><para> + Specifies the type of medium. Valid values are + <literal>disk</literal> (hard drive), + <literal>dvd</literal>, or <literal>floppy</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>filename</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or + absolute path name of the medium or image. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>property-name</replaceable></term> + <listitem><para> + Specifies the name of the property. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-mediumproperty-delete"> + <title>Delete a Medium Property</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage mediumproperty delete</command> command + enables you to delete a medium property. + </para> + <variablelist> + <varlistentry> + <term><literal>disk | dvd | floppy</literal></term> + <listitem><para> + Specifies the type of medium. Valid values are + <literal>disk</literal> (hard drive), + <literal>dvd</literal>, or <literal>floppy</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>filename</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or + absolute path name of the medium or image. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>property-name</replaceable></term> + <listitem><para> + Specifies the name of the property. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command sets the property called + <literal>prop1</literal> to <literal>val1</literal> for the + <filename>ol7.vdi</filename> disk image. + </para> +<screen>$ VBoxManage mediumproperty disk set ol7.vdi prop1 val1</screen> + <para> + The following command gets the value of the property called + <literal>prop1</literal> for the <filename>ol7.vdi</filename> disk + image. + </para> +<screen>$ VBoxManage mediumproperty disk get ol7.vdi prop1</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-metrics.xml b/doc/manual/en_US/man_VBoxManage-metrics.xml new file mode 100644 index 00000000..fcfa10df --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-metrics.xml @@ -0,0 +1,425 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage metrics +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-metrics" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage metrics</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-metrics</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-metrics</refname> + <refpurpose>monitor system resource usage</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-metrics-collect"> + <command>VBoxManage metrics collect</command> + <arg>--detach</arg> + <arg>--list</arg> + <arg>--period=<replaceable>seconds</replaceable></arg> + <arg>--samples=<replaceable>count</replaceable></arg> + <group> + <arg choice="plain">*</arg> + <arg choice="plain">host</arg> + <arg choice="plain"><replaceable>vmname</replaceable> <arg><replaceable>metric-list</replaceable></arg></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-metrics-disable"> + <command>VBoxManage metrics disable</command> + <arg>--list</arg> + <group> + <arg choice="plain">*</arg> + <arg choice="plain">host</arg> + <arg choice="plain"><replaceable>vmname</replaceable> <arg><replaceable>metric-list</replaceable></arg></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-metrics-enable"> + <command>VBoxManage metrics enable</command> + <arg>--list</arg> + <group> + <arg choice="plain">*</arg> + <arg choice="plain">host</arg> + <arg choice="plain"><replaceable>vmname</replaceable> <arg><replaceable>metric-list</replaceable></arg></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-metrics-list"> + <command>VBoxManage metrics list</command> + <group> + <arg choice="plain">*</arg> + <arg choice="plain">host</arg> + <arg choice="plain"><replaceable>vmname</replaceable> <arg><replaceable>metric-list</replaceable></arg></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-metrics-query"> + <command>VBoxManage metrics query</command> + <group> + <arg choice="plain">*</arg> + <arg choice="plain">host</arg> + <arg choice="plain"><replaceable>vmname</replaceable> <arg><replaceable>metric-list</replaceable></arg></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-metrics-setup"> + <command>VBoxManage metrics setup</command> + <arg>--list</arg> + <arg>--period <replaceable>seconds</replaceable></arg> + <arg>--samples <replaceable>count</replaceable></arg> + <group> + <arg choice="plain">*</arg> + <arg choice="plain">host</arg> + <arg choice="plain"><replaceable>vmname</replaceable> <arg><replaceable>metric-list</replaceable></arg></arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage metrics</command> command enables you to + monitor system resource usage for the host system and for virtual + machines (VMs). For example, you can monitor particular metrics, + such as the percentage of time CPUs spend executing in user mode + (<literal>CPU/Load/User</literal>) over a specified sampling + period. + </para> + <para> + While it runs, the <command>VBoxSVC</command> process collects and + saves the specified metric data internally. The + <command>VBoxSVC</command> process runs until shortly after you + close all VMs and frontends. Use the <command>VBoxManage metrics + query</command> command to retrieve data at any time. + </para> + <para> + By default, metrics are not collected unless you run the + <command>VBoxManage metrics setup</command> command to specify a + sampling interval in seconds and the number of metrics to save. + </para> + <para> + Note that you can enable metric collection only for started VMs. + Collected data and collection settings for a VM are discarded when + the VM shuts down. + </para> + <refsect2> + <title>Metrics</title> + <para> + The host and VMs have different sets of associated metrics, + which you can view by running the <command>VBoxManage metrics + list</command> command. + </para> + <para> + Each metric is represented as a string that is composed of a + category and a metric. Optionally, the metric string can include + any of the following: a submetric, a sub-submetric, and an + aggregate. The metric string has the following format: + </para> +<screen><replaceable>category</replaceable>/<replaceable>metric</replaceable>[/<replaceable>submetric</replaceable>[/<replaceable>sub-submetric</replaceable>]][:<replaceable>aggregate</replaceable>]</screen> + <itemizedlist> + <listitem><para> + <replaceable>category</replaceable> is the resource type, + such as <literal>CPU</literal>, <literal>RAM</literal>, + <literal>FS</literal>, <literal>Net</literal>. + </para></listitem> + <listitem><para> + <replaceable>metric</replaceable> is a measurement type that + is associated with the resource category. For example, the + <literal>Load</literal> and <literal>MHz</literal> metrics + are associated with the <literal>CPU</literal> resource + category. + </para></listitem> + <listitem><para> + <replaceable>submetric</replaceable> is an optional + measurement type that is associated with the metric. For + example, the <literal>User</literal>, + <literal>Kernel</literal>, and <literal>Idle</literal> + submetrics are associated with the <literal>Load</literal> + metric. + </para></listitem> + <listitem><para> + <replaceable>sub-submetric</replaceable> is an optional + measurement type that is associated with the submetric. For + example, the <literal>Rx</literal> and <literal>Tx</literal> + sub-submetrics are associated with the + <literal>Rate</literal> submetric of the + <literal>Net</literal> resource category. The associated + metric is the network interface. + </para></listitem> + <listitem><para> + <replaceable>aggregate</replaceable> is an optional function + to provide minimum, maximum, and average measurements for a + resource category. For example, the + <literal>RAM/Usage/Free:min</literal> metric represents the + minimum amount of available memory found in all saved data + on the host system. + </para></listitem> + </itemizedlist> + <para> + By default, the <command>VBoxManage metrics</command> commands + operate on the host system and all VMs, and report on all + metrics. You can optionally limit these commands to operate on + the host system or on a particular VM, and report on a list of + one or more metrics. + </para> + </refsect2> + <refsect2 id="vboxmanage-metrics-common-options"> + <title>Common Options</title> + <variablelist> + <varlistentry> + <term><literal>*</literal> | <literal>host</literal> | <replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the component on which to operate. By default, + this command operates on the host system and all running + VMs. + </para><para> + If you specify <literal>host</literal>, the + <command>VBoxManage metrics</command> command operates on + the host system only. If you specify an asterisk + (<literal>*</literal>), the command operates on all VMs. + If you specify the name of a VM, the <command>VBoxManage + metrics</command> command operates on that VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>metric-list</replaceable></term> + <listitem><para> + Specifies a comma-separated list of one or more metrics. + </para><para> + The form of the metric must include the + <replaceable>category</replaceable> and + <replaceable>metric</replaceable> part of the metric + string separated by a slash. + </para><para> + Note that the <command>VBoxManage metrics enable</command> + and <command>VBoxManage metrics disable</command> commands + require that you specify metrics as parameters. The + metrics must include only the resource category and metric + part, such as <literal>CPU/Load</literal> and + <literal>RAM/Usage</literal>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-metrics-collect"> + <title>Collect Data Metrics</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage metrics collect</command> command + collects and outputs data periodically until you stop the + process by pressing Ctrl+C. + </para> + <variablelist> + <varlistentry> + <term><option>--detach</option></term> + <listitem><para> + Disables the collection of metric data, so no data is + output. Using this option is the same as running the + <command>VBoxManage metrics setup</command> command. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--list</option></term> + <listitem><para> + Shows which metrics match the specified filter. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--period=<replaceable>seconds</replaceable></option></term> + <listitem><para> + Specifies the number of seconds to wait between collecting + metric data samples. The default value is 1. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--samples=<replaceable>count</replaceable></option></term> + <listitem><para> + Specifies the number of metric data samples to save. To + view the saved data, use the <command>VBoxManage metrics + query</command> command. The default value is 1. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-metrics-disable"> + <title>Disable Metric Data Collection</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage metrics disable</command> command + suspends data collection. This action does not affect the data + collection properties or the collected data. Note that + specifying a submetric in the metric list does not disable its + underlying metrics. + </para> + <para> + Note that the <command>VBoxManage metrics disable</command> + command requires that you specify metrics as parameters. The + metrics must include only the resource category and metric part, + such as <literal>CPU/Load</literal> and + <literal>RAM/Usage</literal>. + </para> + <variablelist> + <varlistentry> + <term><option>--list</option></term> + <listitem><para> + Shows whether the command succeeded as expected. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-metrics-enable"> + <title>Enable Metric Data Collection</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage metrics enable</command> command resumes + data collection after it has been suspended by using the + <command>VBoxManage metrics disable</command> command. Note that + specifying a submetric in the metric list does not enable its + underlying metrics. + </para> + <para> + Unlike the <command>VBoxManage metrics setup</command> command, + the <command>VBoxManage metrics enable</command> command does + not discard previously collected samples for the specified set + of objects and metrics. + </para> + <para> + Note that the <command>VBoxManage metrics enable</command> + command requires that you specify metrics as parameters. The + metrics must include only the resource category and metric part, + such as <literal>CPU/Load</literal> and + <literal>RAM/Usage</literal>. + </para> + <variablelist> + <varlistentry> + <term><option>--list</option></term> + <listitem><para> + Shows whether the command succeeded as expected. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-metrics-list"> + <title>List Metric Values</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage metrics list</command> command shows the + metrics that are currently available. Note that VM-specific + metrics are shown only when that VM is running. + </para> + </refsect2> + <refsect2 id="vboxmanage-metrics-query"> + <title>List Saved Metric Data</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage metrics query</command> command + retrieves and shows the saved metric data. + </para> + <para> + Note that the <command>VBoxManage metrics query</command> + command does not remove or flush saved data but older samples + are replaced by newer samples over time. + </para> + </refsect2> + <refsect2 id="vboxmanage-metrics-setup"> + <title>Configure Metric-Gathering Properties</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage metrics setup</command> command + configures metric-gathering properties. + </para> + <para> + Note that this command discards any previously collected samples + for the specified set of objects and metrics. To enable or + disable metrics collection without discarding the data, use the + <command>VBoxManage metrics enable</command> command or the + <command>VBoxManage metrics disable</command> command, + respectively. + </para> + <variablelist> + <varlistentry> + <term><option>--list</option></term> + <listitem><para> + Shows which metrics have been modified as a result of the + command execution. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--period=<replaceable>seconds</replaceable></option></term> + <listitem><para> + Specifies the number of seconds to wait between collecting + metric data samples. The default value is 1. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--samples=<replaceable>count</replaceable></option></term> + <listitem><para> + Specifies the number of metric data samples to save. To + view the saved data, use the <command>VBoxManage metrics + query</command> command. The default value is 1. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following example command enables the collection of host + processor and memory usage metrics every second. The + <option>--samples</option> option saves the five latest samples. + </para> +<screen>$ VBoxManage metrics setup --period 1 --samples 5 host CPU/Load,RAM/Usage</screen> + <para> + The following command lists the metrics that are available to the + host system and VMs: + </para> +<screen>$ VBoxManage metrics list</screen> + <para> + Note that the host system and VMs have different sets of metrics. + </para> + <para> + The following example shows how to query metric data about the CPU + time spent in user and kernel modes for the + <literal>test</literal> VM: + </para> +<screen>$ VBoxManage metrics query test CPU/Load/User,CPU/Load/Kernel</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-modifymedium.xml b/doc/manual/en_US/man_VBoxManage-modifymedium.xml new file mode 100644 index 00000000..5bb48e09 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-modifymedium.xml @@ -0,0 +1,256 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage modifymedium +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-modifymedium" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage modifymedium</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-modifymedium</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-modifymedium</refname> + <refpurpose>change the characteristics of an existing disk image</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-modifymedium"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage modifymedium</command> + <group> + <arg choice="plain">disk</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">floppy</arg> + </group> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>filename</replaceable></arg> + </group> + <arg>--autoreset=on | off</arg> + <arg>--compact</arg> + <arg>--description=<replaceable>description</replaceable></arg> + <arg>--move=<replaceable>pathname</replaceable></arg> + <arg>--property=<replaceable>name</replaceable>=[<replaceable>value</replaceable>]</arg> + <arg>--resize=<replaceable>megabytes</replaceable> | --resizebyte=<replaceable>bytes</replaceable></arg> + <arg>--setlocation=<replaceable>pathname</replaceable></arg> + <arg>--type=normal | writethrough | immutable | shareable | readonly | multiattach</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage modifymedium</command> command enables you + to change the characteristics of an existing disk image. + </para> + <note> + <para> + For compatibility with earlier versions of &product-name;, you + can use the <command>modifyvdi</command> and + <command>modifyhd</command> commands. + </para> + </note> + <variablelist> + <varlistentry> + <term>disk | dvd | floppy</term> + <listitem><para> + Specifies the media type of the image. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>filename</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or path + name of the disk image on the host file system. You can + specify the UUID only if the medium is registered. Use the + <command>VBoxManage list hdds</command> command to list the + registered images. You can specfy an absolute or relative + path to the medium. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--autoreset=on | off</option></term> + <listitem><para> + Specifies whether to automatically reset an immutable hard + disk on every virtual machine (VM) startup. This option is + only for immutable hard disks and the default value is + <literal>on</literal>. See <xref linkend="hdimagewrites" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--compact</option></term> + <listitem><para> + Compresses disk images by removing blocks that contain only + zeroes. This option shrinks a dynamically allocated image + and reduces the <emphasis>physical</emphasis> size of the + image without affecting the logical size of the virtual + disk. + </para><para> + You can use this option for base images and for differencing + images that are created as part of a snapshot. + </para><note> + <para> + Before you compress the image, you must use a suitable + software tool to zero out free space in the guest system. + For example: + </para> + <itemizedlist> + <listitem><para> + <emphasis role="bold">Windows guests.</emphasis> Run + the <command>sdelete -z</command> command. + </para></listitem> + <listitem><para> + <emphasis role="bold">Linux guests.</emphasis> Use the + <command>zerofree</command> utility, which supports + <literal>ext2</literal> and <literal>ext3</literal> + file systems. + </para></listitem> + <listitem><para> + <emphasis role="bold">Mac OS X guests.</emphasis> Use + the <command>diskutil secureErase freespace 0 + /</command> command. + </para></listitem> + </itemizedlist> + </note><para> + Note that you can only use this option to compress VDI + images. To compress non-VID images, you can zero out free + blocks and then clone the disk to any other dynamically + allocated format. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--description=<replaceable>description</replaceable></option></term> + <listitem><para> + Specifies a text description of the medium. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--move=<replaceable>pathname</replaceable></option></term> + <listitem><para> + Specifies a relative or absolute path to a medium on the + host system. Use this option to relocate a medium to a + different location on the host system. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--property=<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies a property name and value for the medium. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--resize=<replaceable>size</replaceable></option></term> + <listitem><para> + Specifes the new capacity of an existing image in MB. You + can use this option only to expand the capacity of an image. + You can cannot shrink the capacity of an image. + </para><para> + Note that you can resize only dynamically allocated disk + images that use the VDI and VHD formats. This option adjusts + the <emphasis>logical</emphasis> size of a virtual disk and + has only a minor affect on the physical size. + </para><para> + For example, if your dynamically allocated 10 GB disk is + full, you can use the <option>--resize 15360</option> option + to increase the capacity of the existing disk to 15 GB + (15,360 MB). This operation enables you to avoid having to + create a new image and copy all data from within a VM. + </para><para> + Note that using this option only changes the capacity of the + drive. So, you might need to subsequently use a partition + management tool in the guest to adjust the main partition to + fill the drive. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--resizebyte=<replaceable>size</replaceable></option></term> + <listitem><para> + Specifes the new capacity of an existing image in bytes. + This option is similar to the <option>--resize</option> + option, but you specify the size in bytes instead of + megabytes. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--setlocation=<replaceable>pathname</replaceable></option></term> + <listitem><para> + Specifies the new location of the medium on the host system + after the medium has been moved. The path name can be + relative to the current directory or be absolute to the + root. + </para><para> + Note that the <command>VBoxManage modifymedium</command> + command does not perform any sanity checks on the path name + you specify. Ensure that the path name is valid. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--type</option></term> + <listitem><para> + Specifies the new mode type of an existing image. Valid + values are <literal>normal</literal>, + <literal>immutable</literal>, + <literal>writethrough</literal>, + <literal>multi-attach</literal>, + <literal>shareable</literal>, and + <literal>readonly</literal>. For descriptions of these mode + types, see <xref linkend="hdimagewrites" />. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command modifies the description for the disk image + file called <filename>disk01.vdi</filename>. + </para> +<screen>$ VBoxManage modifymedium disk disk01.vdi --description "Oracle Linux 7 image"</screen> + <para> + The following command modifies the write mode for the disk image + file called <filename>disk01.vdi</filename>. + </para> +<screen>$ VBoxManage modifymedium disk disk01.vdi --type writethrough</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-list" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-modifynvram.xml b/doc/manual/en_US/man_VBoxManage-modifynvram.xml new file mode 100644 index 00000000..63ea3223 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-modifynvram.xml @@ -0,0 +1,248 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage modifynvram +--> +<!-- + Copyright (C) 2021-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-modifynvram" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-04-06 11:27:32 +0200 (Thu, 06 Apr 2023) $</pubdate> + <title>VBoxManage modifynvram</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-modifynvram</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-modifynvram</refname> + <refpurpose>List and modify the NVRAM content of a virtual machine</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-inituefivarstore"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">inituefivarstore</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-enrollmssignatures"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">enrollmssignatures</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-enrollorclpk"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">enrollorclpk</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-enrollpk"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">enrollpk</arg> + <arg>--platform-key=<replaceable>filename</replaceable></arg> + <arg>--owner-uuid=<replaceable>uuid</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-enrollmok"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">enrollmok</arg> + <arg>--mok=<replaceable>filename</replaceable></arg> + <arg>--owner-uuid=<replaceable>uuid</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-listvars"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">listvars</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-queryvar"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">queryvar</arg> + <arg>--name=<replaceable>name</replaceable></arg> + <arg>--filename=<replaceable>filename</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-deletevar"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">deletevar</arg> + <arg>--name=<replaceable>name</replaceable></arg> + <arg>--owner-uuid=<replaceable>uuid</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-changevar"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">changevar</arg> + <arg>--name=<replaceable>name</replaceable></arg> + <arg>--filename=<replaceable>filename</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The "modifynvram" commands are for experts who want to inspect and modify the + UEFI variable store of a virtual machine. Any mistakes done here can bring the virtual + machine in a non working state.</para> + + <refsect2 id="vboxmanage-modifynvram-common-options"> + <title>Common options</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>The subcommands of <command>modifynvram</command> all operate on a running virtual + machine:</para> + <variablelist> + <varlistentry> + <term><replaceable>uuid|vmname</replaceable></term> + <listitem><para>Either the UUID or the name (case sensitive) of a VM.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-inituefivarstore"> + <title>modifynvram inituefivarstore</title> + <remark role="help-copy-synopsis"/> + <para> + Iniitalizes the UEFI variable store to a default state. Any previous existing variable + store is deleted. Use with extreme caution! + </para> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-enrollmssignatures"> + <title>modifynvram enrollmssignatures</title> + <remark role="help-copy-synopsis"/> + <para> + Enrolls the default Microsoft KEK and DB signatures required for UEFI secure boot. + </para> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-enrollorclpk"> + <title>modifynvram enrollorclpk</title> + <remark role="help-copy-synopsis"/> + <para> + Enrolls the default platform key provided by Oracle required for UEFI secure boot. + </para> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-enrollpk"> + <title>modifynvram enrollpk</title> + <remark role="help-copy-synopsis"/> + <para> + Enrolls a custom platform key provided by the user required for UEFI secure boot. + The following commands use openssl to generate a new platform key: + </para> +<screen>$ openssl req -new -x509 -newkey rsa:2048 -keyout PK.key -out PK.crt</screen> +<screen>$ openssl x509 -in PK.crt -out PK.cer -outform DER</screen> + <variablelist> + <varlistentry> + <term><option>--platform-key=<replaceable>filename</replaceable></option></term> + <listitem><para>The platform key provided as a DER encoded X.509 signature.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--owner-uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para>The UUID identifying the owner of the platform key.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-listvars"> + <title>modifynvram listvars</title> + <remark role="help-copy-synopsis"/> + <para> + Lists all UEFI variables in the virtual machines's store along with their owner UUID. + </para> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-queryvar"> + <title>modifynvram queryvar</title> + <remark role="help-copy-synopsis"/> + <para> + Queries the content of a given UEFI variable identified by its name. + </para> + <variablelist> + <varlistentry> + <term><option>--name=<replaceable>name</replaceable></option></term> + <listitem><para>UEFI variable name to query.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--filename=<replaceable>filename</replaceable></option></term> + <listitem> + <para> + Where to store the content of the variable upon success. This is optional, + if omitted the content will be dumped to the terminal as a hex dump. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-deletevar"> + <title>modifynvram deletevar</title> + <remark role="help-copy-synopsis"/> + <para> + Deletes the given variable identified by its name and owner UUID. + </para> + <variablelist> + <varlistentry> + <term><option>--name=<replaceable>name</replaceable></option></term> + <listitem><para>UEFI variable name to delete.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--owner-uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para>The UUID identifying the owner of the variable to delete.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-changevar"> + <title>modifynvram changevar</title> + <remark role="help-copy-synopsis"/> + <para> + Changes the UEFI variable content to the one form the given file. + </para> + <variablelist> + <varlistentry> + <term><option>--name=<replaceable>name</replaceable></option></term> + <listitem><para>UEFI variable name to change the data for.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--filename=<replaceable>filename</replaceable></option></term> + <listitem> + <para>The file to read the data from.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-modifyvm.xml b/doc/manual/en_US/man_VBoxManage-modifyvm.xml new file mode 100644 index 00000000..9916b604 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-modifyvm.xml @@ -0,0 +1,2818 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage modifyvm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-modifyvm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage modifyvm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-modifyvm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-modifyvm</refname> + <refpurpose>Change settings for a virtual machine that is stopped</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-general"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--name=<replaceable>name</replaceable></arg> + <arg>--groups= <arg choice="plain"><replaceable>group</replaceable> [,<replaceable>group</replaceable>...]</arg></arg> + <arg>--description=<replaceable>description</replaceable></arg> + <arg>--os-type=<replaceable>OS-type</replaceable></arg> + <arg>--icon-file=<replaceable>filename</replaceable></arg> + <arg>--memory=<replaceable>size-in-MB</replaceable></arg> + <arg>--page-fusion=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vram=<replaceable>size-in-MB</replaceable></arg> + <arg>--acpi=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--ioapic=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--hardware-uuid=<replaceable>UUID</replaceable></arg> + <arg>--cpus=<replaceable>CPU-count</replaceable></arg> + <arg>--cpu-hotplug=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--plug-cpu=<replaceable>CPU-ID</replaceable></arg> + <arg>--unplug-cpu=<replaceable>CPU-ID</replaceable></arg> + <arg>--cpu-execution-cap=<replaceable>number</replaceable></arg> + <arg>--pae=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--long-mode=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--ibpb-on-vm-exit=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--ibpb-on-vm-entry=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--spec-ctrl=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--l1d-flush-on-sched=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--l1d-flush-on-vm-entry=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--mds-clear-on-sched=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--mds-clear-on-vm-entry=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--cpu-profile=<group choice="plain"> + <arg choice="plain">host</arg> + <arg choice="plain">Intel 8086</arg> + <arg choice="plain">Intel 80286</arg> + <arg choice="plain">Intel 80386</arg> + </group></arg> + <arg>--hpet=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--hwvirtex=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--triple-fault-reset=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--apic=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--x2apic=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--paravirt-provider=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">default</arg> + <arg choice="plain">legacy</arg> + <arg choice="plain">minimal</arg> + <arg choice="plain">hyperv</arg> + <arg choice="plain">kvm</arg> + </group></arg> + <arg>--paravirt-debug= <arg choice="plain"><replaceable>key</replaceable>=<replaceable>value</replaceable> [,<replaceable>key</replaceable>=<replaceable>value</replaceable>...]</arg></arg> + <arg>--nested-paging=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--large-pages=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vtx-vpid=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vtx-ux=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nested-hw-virt=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--virt-vmsave-vmload=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--accelerate-3d=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--accelerate-2d-video=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--chipset=<group choice="plain"> + <arg choice="plain">ich9</arg> + <arg choice="plain">piix3</arg> + </group></arg> + <arg>--iommu=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">automatic</arg> + <arg choice="plain">amd</arg> + <arg choice="plain">intel</arg> + </group></arg> + <arg>--tpm-type=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">1.2</arg> + <arg choice="plain">2.0</arg> + <arg choice="plain">host</arg> + <arg choice="plain">swtpm</arg> + </group></arg> + <arg>--tpm-location=<group choice="plain"> + <arg choice="plain"><replaceable>location</replaceable></arg> + </group></arg> + <arg>--bios-logo-fade-in=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--bios-logo-fade-out=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--bios-logo-display-time=<replaceable>msec</replaceable></arg> + <arg>--bios-logo-image-path=<replaceable>pathname</replaceable></arg> + <arg>--bios-boot-menu=<group choice="plain"> + <arg choice="plain">disabled</arg> + <arg choice="plain">menuonly</arg> + <arg choice="plain">messageandmenu</arg> + </group></arg> + <arg>--bios-apic=<group choice="plain"> + <arg choice="plain">disabled</arg> + <arg choice="plain">apic</arg> + <arg choice="plain">x2apic</arg> + </group></arg> + <arg>--bios-system-time-offset=<replaceable>msec</replaceable></arg> + <arg>--bios-pxe-debug=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--system-uuid-le=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--boot<replaceable>X</replaceable>=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">floppy</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">disk</arg> + <arg choice="plain">net</arg> + </group></arg> + <arg>--rtc-use-utc=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--graphicscontroller=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">vboxvga</arg> + <arg choice="plain">vmsvga</arg> + <arg choice="plain">vboxsvga</arg> + </group></arg> + <arg>--snapshot-folder=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain"><replaceable>pathname</replaceable></arg> + </group></arg> + <arg>--firmware=<group choice="plain"> + <arg choice="plain">bios</arg> + <arg choice="plain">efi</arg> + <arg choice="plain">efi32</arg> + <arg choice="plain">efi64</arg> + </group></arg> + <arg>--guest-memory-balloon=<replaceable>size-in-MB</replaceable></arg> + <arg>--default-frontend=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain"><replaceable>name</replaceable></arg> + </group></arg> +<!-- There are currently undocumented options --iocache and +--iocachesize which are scheduled for removal. Not worth spending +time on documenting it. --> + <arg>--vm-process-priority=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain">flat</arg> + <arg choice="plain">low</arg> + <arg choice="plain">normal</arg> + <arg choice="plain">high</arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-networking"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--nic<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">null</arg> + <arg choice="plain">nat</arg> + <arg choice="plain">bridged</arg> + <arg choice="plain">intnet</arg> + <arg choice="plain">hostonly</arg> + <arg choice="plain">hostonlynet</arg> + <arg choice="plain">generic</arg> + <arg choice="plain">natnetwork</arg> + <arg choice="plain">cloud</arg> + </group></arg> + <arg>--nic-type<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">Am79C970A</arg> + <arg choice="plain">Am79C973</arg> + <arg choice="plain">82540EM</arg> + <arg choice="plain">82543GC</arg> + <arg choice="plain">82545EM</arg> + <arg choice="plain">virtio</arg> + </group></arg> + <arg>--cable-connected<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nic-trace<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nic-trace-file<replaceable>N</replaceable>=<replaceable>filename</replaceable></arg> + <arg>--nic-property<replaceable>N</replaceable>=<replaceable>name</replaceable>= <arg><replaceable>value</replaceable></arg></arg> + <arg>--nic-speed<replaceable>N</replaceable>=<replaceable>kbps</replaceable></arg> + <arg>--nic-boot-prio<replaceable>N</replaceable>=<replaceable>priority</replaceable></arg> + <arg>--nic-promisc<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">deny</arg> + <arg choice="plain">allow-vms</arg> + <arg choice="plain">allow-all</arg> + </group></arg> + <arg>--nic-bandwidth-group<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain"><replaceable>name</replaceable></arg> + </group></arg> + <arg>--bridge-adapter<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain"><replaceable>device-name</replaceable></arg> + </group></arg> + <arg>--cloud-network<replaceable>N</replaceable>=<replaceable>network-name</replaceable></arg> + <arg>--host-only-adapter<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain"><replaceable>device-name</replaceable></arg> + </group></arg> + <arg>--host-only-net<replaceable>N</replaceable>=<replaceable>network-name</replaceable></arg> + <arg>--intnet<replaceable>N</replaceable>=<replaceable>network-name</replaceable></arg> + <arg>--nat-network<replaceable>N</replaceable>=<replaceable>network-name</replaceable></arg> + <arg>--nic-generic-drv<replaceable>N</replaceable>=<replaceable>driver-name</replaceable></arg> + <arg>--mac-address<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">auto</arg> + <arg choice="plain"><replaceable>MAC-address</replaceable></arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-networking-nat"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--nat-net<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain"><replaceable>network</replaceable></arg> + <arg choice="plain">default</arg> + </group></arg> + <arg>--nat-pf<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">[<replaceable>rule-name</replaceable>],tcp</arg> + <arg choice="plain">udp,[<replaceable>host-IP</replaceable>],<replaceable>hostport</replaceable>,[<replaceable>guest-IP</replaceable>],<replaceable>guestport</replaceable></arg> + </group></arg> + <arg>--nat-pf<replaceable>N</replaceable>=delete=<replaceable>rule-name</replaceable></arg> + <arg>--nat-tftp-prefix<replaceable>N</replaceable>=<replaceable>prefix</replaceable></arg> + <arg>--nat-tftp-file<replaceable>N</replaceable>=<replaceable>filename</replaceable></arg> + <arg>--nat-tftp-server<replaceable>N</replaceable>=<replaceable>IP-address</replaceable></arg> + <arg>--nat-bind-ip<replaceable>N</replaceable>=<replaceable>IP-address</replaceable></arg> + <arg>--nat-dns-pass-domain<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nat-dns-proxy<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nat-dns-host-resolver<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nat-localhostreachable<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nat-settings<replaceable>N</replaceable>=[<replaceable>mtu</replaceable>],[<replaceable>socksnd</replaceable>],[<replaceable>sockrcv</replaceable>],[<replaceable>tcpsnd</replaceable>],[<replaceable>tcprcv</replaceable>]</arg> + <arg>--nat-alias-mode<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain">[log],[proxyonly],[sameports]</arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-other-hardware"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--mouse=<group choice="plain"> + <arg choice="plain">ps2</arg> + <arg choice="plain">usb</arg> + <arg choice="plain">usbtablet</arg> + <arg choice="plain">usbmultitouch</arg> + <arg choice="plain">usbmtscreenpluspad</arg> + </group></arg> + <arg>--keyboard=<group choice="plain"> + <arg choice="plain">ps2</arg> + <arg choice="plain">usb</arg> + </group></arg> + <arg>--uart<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">off</arg> + <arg choice="plain"><replaceable>IO-base</replaceable> <replaceable>IRQ</replaceable></arg> + </group></arg> + <arg>--uart-mode<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">disconnected</arg> + <arg choice="plain">server <replaceable>pipe</replaceable></arg> + <arg choice="plain">client <replaceable>pipe</replaceable></arg> + <arg choice="plain">tcpserver <replaceable>port</replaceable></arg> + <arg choice="plain">tcpclient <replaceable>hostname</replaceable>:<replaceable>port</replaceable></arg> + <arg choice="plain">file <replaceable>filename</replaceable></arg> + <arg choice="plain"><replaceable>device-name</replaceable></arg> + </group></arg> + <arg>--uart-type<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">16450</arg> + <arg choice="plain">16550A</arg> + <arg choice="plain">16750</arg> + </group></arg> + <arg>--lpt-mode<replaceable>N</replaceable>=<replaceable>device-name</replaceable></arg> + <arg>--lpt<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">off</arg> + <arg choice="plain"><replaceable>IO-base</replaceable> <replaceable>IRQ</replaceable></arg> + </group></arg> + <arg>--audio-controller=<group choice="plain"> + <arg choice="plain">ac97</arg> + <arg choice="plain">hda</arg> + <arg choice="plain">sb16</arg> + </group></arg> + <arg>--audio-codec=<group choice="plain"> + <arg choice="plain">stac9700</arg> + <arg choice="plain">ad1980</arg> + <arg choice="plain">stac9221</arg> + <arg choice="plain">sb16</arg> + </group></arg> + <arg>--audio-driver=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">default</arg> + <arg choice="plain">null</arg> + <arg choice="plain">dsound</arg> + <arg choice="plain">was</arg> + <arg choice="plain">oss</arg> + <arg choice="plain">alsa</arg> + <arg choice="plain">pulse</arg> + <arg choice="plain">coreaudio</arg> + </group></arg> + <arg>--audio-enabled=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--audio-in=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--audio-out=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--clipboard-mode=<group choice="plain"> + <arg choice="plain">disabled</arg> + <arg choice="plain">hosttoguest</arg> + <arg choice="plain">guesttohost</arg> + <arg choice="plain">bidirectional</arg> + </group></arg> +<!-- There is a currently undocumented option --clipboard-file-transfers. +The implementation is not finished, so postpone documenting until it +actually is ready for users. --> + <arg>--drag-and-drop=<group choice="plain"> + <arg choice="plain">disabled</arg> + <arg choice="plain">hosttoguest</arg> + <arg choice="plain">guesttohost</arg> + <arg choice="plain">bidirectional</arg> + </group></arg> + <arg>--monitor-count=<replaceable>number</replaceable></arg> + <arg>--usb-ehci=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--usb-ohci=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--usb-xhci=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--usb-rename=<replaceable>old-name</replaceable> <replaceable>new-name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-recording"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--recording=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--recording-screens=<group choice="plain"> + <arg choice="plain">all</arg> + <arg choice="plain">none</arg> + <arg choice="plain"><replaceable>screen-ID</replaceable>[,<replaceable>screen-ID</replaceable>...]</arg> + </group></arg> + <arg>--recording-file=<replaceable>filename</replaceable></arg> + <arg>--recording-max-size=<replaceable>MB</replaceable></arg> + <arg>--recording-max-time=<replaceable>msec</replaceable></arg> + <arg>--recording-opts= <arg choice="plain"><replaceable>key</replaceable>=<replaceable>value</replaceable>[,<replaceable>key</replaceable>=<replaceable>value</replaceable>...]</arg></arg> + <arg>--recording-video-fps=<replaceable>fps</replaceable></arg> + <arg>--recording-video-rate=<replaceable>rate</replaceable></arg> + <arg>--recording-video-res=<replaceable>width</replaceable> <replaceable>height</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-vrde"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--vrde=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vrde-property=<replaceable>property-name</replaceable>= <arg><replaceable>property-value</replaceable></arg></arg> + <arg>--vrde-extpack=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain"><replaceable>name</replaceable></arg> + </group></arg> + <arg>--vrde-port=<replaceable>port</replaceable></arg> + <arg>--vrde-address=<replaceable>hostip</replaceable></arg> + <arg>--vrde-auth-type=<group choice="plain"> + <arg choice="plain">null</arg> + <arg choice="plain">external</arg> + <arg choice="plain">guest</arg> + </group></arg> + <arg>--vrde-auth-library=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain"><replaceable>name</replaceable></arg> + </group></arg> + <arg>--vrde-multi-con=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vrde-reuse-con=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vrde-video-channel=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vrde-video-channel-quality=<replaceable>percent</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-teleport"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--teleporter=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--teleporter-port=<replaceable>port</replaceable></arg> + <arg>--teleporter-address=<group choice="plain"> + <arg choice="plain"><replaceable>address</replaceable></arg> + <arg choice="plain">empty</arg> + </group></arg> + <arg>--teleporter-password=<replaceable>password</replaceable></arg> + <arg>--teleporter-password-file=<group choice="plain"> + <arg choice="plain"><replaceable>filename</replaceable></arg> + <arg choice="plain">stdin</arg> + </group></arg> + <arg>--cpuid-portability-level=<replaceable>level</replaceable></arg> + <arg>--cpuid-set=<replaceable>leaf</replaceable><arg>:<replaceable>subleaf</replaceable></arg> <replaceable>eax</replaceable> <replaceable>ebx</replaceable> <replaceable>ecx</replaceable> <replaceable>edx</replaceable></arg> + <arg>--cpuid-remove=<replaceable>leaf</replaceable><arg>:<replaceable>subleaf</replaceable></arg></arg> + <arg>--cpuid-remove-all</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-debugging"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--tracing-enabled=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--tracing-config=<replaceable>string</replaceable></arg> + <arg>--tracing-allow-vm-access=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-usbcardreader"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--usb-card-reader=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-autostart"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--autostart-enabled=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--autostart-delay=<replaceable>seconds</replaceable></arg> +<!-- There is a currently undocumented option --autostop-type. +Most autostart service implementations either ignore it or rely it is +left unchanged due to otherwise running into timeouts established by the +host OS, defeating the purpose. Not worth spending time on documenting +it unless this changes. --> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-guest-debug"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--guest-debug-provider=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">native</arg> + <arg choice="plain">gdb</arg> + <arg choice="plain">kd</arg> + </group></arg> + <arg>--guest-debug-io-provider=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">tcp</arg> + <arg choice="plain">udp</arg> + <arg choice="plain">ipc</arg> + </group></arg> + <arg>--guest-debug-address=<group choice="plain"> + <arg choice="plain"><replaceable>IP-Address</replaceable></arg> + <arg choice="plain"><replaceable>path</replaceable></arg> + </group></arg> + <arg>--guest-debug-port=<replaceable>port</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-pcipassthrough"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--pci-attach=<replaceable>host-PCI-address</replaceable><arg>@<replaceable>guest-PCI-bus-address</replaceable></arg></arg> + <arg>--pci-detach=<replaceable>host-PCI-address</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-testing"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--testing-enabled=<group choice="plain"><arg choice="plain">on</arg><arg choice="plain">off</arg></group></arg> + <arg>--testing-mmio=<group choice="plain"><arg choice="plain">on</arg><arg choice="plain">off</arg></group></arg> + <arg>--testing-cfg-dword<replaceable>idx</replaceable>=<replaceable>value</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage modifyvm</command> command enables you to + change the properties of a registered virtual machine (VM) that is + not running. + </para> + <para> + Most of these properties correspond to the VM settings that are + shown in each VM's <emphasis role="bold">Settings</emphasis> + dialog in the VirtualBox Manager. See + <xref linkend="BasicConcepts" />. However, some settings can only + be viewed and managed with the <command>VBoxManage</command> + command. + </para> + <para> + You can use the <command>VBoxManage modifyvm</command> command to + change VM settings only when the VM is powered off. The VM cannot + be running or in saved state when you use this command. + </para> + <para> + You can use the <command>VBoxManage controlvm</command> command to + dynamically change some VM machine settings while the VM is + running. See <xref linkend="vboxmanage-controlvm" />. + </para> + <refsect2 id="vboxmanage-modifyvm-general"> + <title>General Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The following options enable you to modify general information + about your VM. + </para> + <para> + The <command>VBoxManage modifyvm</command> command supports the + following options: + </para> + <variablelist> + <varlistentry> + <term><option>--name=<replaceable>vmname</replaceable></option></term> + <listitem><para> + Changes the name of the VM and its related internal VM + files. See <xref linkend="vboxmanage-createvm"/>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--groups=<replaceable>group</replaceable></option></term> + <listitem><para> + Changes the group membership of a VM. Group names always + begin with a slash character (<literal>/</literal>) and + can be nested. By default, VMs are members of the + <literal>/</literal> group. A VM can be member of multiple + groups, but its primary group determines the directory + structure where the internal VM files are placed by default. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--description=<replaceable>desc</replaceable></option></term> + <listitem><para> + Changes the optional VM description. Use a description to + record details about the VM in a meaningful way. The GUI + interprets HTML markup while the <command>VBoxManage + modifyvm</command> command enables you include arbitrary + strings that can contain multiple lines. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--os-type=<replaceable>OS-type</replaceable></option></term> + <listitem><para> + Specifies the guest operating system (OS) information for + the VM. Use the <command>VBoxManage list ostypes</command> + command to view the OS type identifiers. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--icon-file=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies the path to the VM icon file in PNG format + on the host system. The icon is shown in the VM manager + UI and when running the VM with UI. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--memory=<replaceable>size</replaceable></option></term> + <listitem><para> + Specifies the amount of host system RAM to allocate to the + VM. The size is in MB. See + <xref linkend="create-vm-wizard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--page-fusion=on | off</option></term> + <listitem><para> + Enables or disables the Page Fusion feature, which is + disabled by default. Use the Page Fusion feature to + minimize the memory duplication between VMs that have + similar configurations and that run on the same host + system. See <xref linkend="guestadd-pagefusion" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vram=<replaceable>size</replaceable></option></term> + <listitem><para> + Specifies the amount of RAM to allocate to the virtual + graphics card. See <xref linkend="settings-display" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--acpi=on | off</option></term> + <listitem><para> + Determines whether the VM has ACPI support. See + <xref linkend="settings-motherboard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ioapic=on | off</option></term> + <listitem><para> + Determines whether the VM has I/O APIC support. See + <xref linkend="settings-motherboard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--hardware-uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) to + present to the guest VM in memory tables (DMI/SMBIOS), + hardware, and VM properties. By default this hardware UUID + is the same as the VM UUID. Cloning a VM and the teleporting + feature automatically preserve the hardware UUID value. + Likewise for Virtual Appliance export and import, but only + if both operations are done by &product-name;. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpus=<replaceable>CPU-count</replaceable></option></term> + <listitem><para> + Specifies the number of virtual CPUs to assign to the VM. + See <xref linkend="settings-processor" />. + </para><para> + If CPU hot-plugging is enabled, this option specifies the + maximum number of virtual CPUs that can be plugged into + the VMs. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpu-hotplug=on | off</option></term> + <listitem><para> + Enables or disables CPU hot-plugging. When enabled, you + can dynamically add virtual CPUs to a VM or remove virtual + CPUs from a VM. See <xref linkend="cpuhotplug" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--plug-cpu=<replaceable>CPU-ID</replaceable></option></term> + <listitem><para> + Adds a virtual CPU to the VM. + <replaceable>CPU-ID</replaceable> is the index of the + virtual CPU to add. A valid index value is a number from + <literal>0</literal> to the maximum number of CPUs that + you configured by using the <option>--cpus</option> + option. + </para><para> + Only use this option if CPU hot-plugging is enabled. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unplug-cpu=<replaceable>CPU-ID</replaceable></option></term> + <listitem><para> + Removes a virtual CPU from the VM. + <replaceable>CPU-ID</replaceable> is the index of the + virtual CPU to remove. A valid index value is a number + from <literal>1</literal> to the maximum number of CPUs + that you configured by using the <option>--cpus</option> + option. + </para><para> + Only use this option if CPU hot-plugging is enabled. + </para><para> + Note that you cannot remove CPU 0. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpuexectioncap=<replaceable>percentage</replaceable></option></term> + <listitem> + <para> + Specifies how much CPU time a virtual CPU can use. A valid + value is from <literal>1</literal> to + <literal>100</literal>. A value of 50 indicates that a + single virtual CPU can use up to 50% of a single host CPU. + </para> + <para> + Use this feature with caution, it can have unexpected results + including timekeeping problems and lower performance than + specified. If you want to limit the resource usage of a VM + it is more reliable to pick an appropriate number of VCPUs. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--pae=on | off</option></term> + <listitem><para> + Enables or disables physical address extension (PAE). See + <xref linkend="settings-processor" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--long-mode=on | off</option></term> + <listitem><para> + Enables or disables long mode. See + <xref linkend="settings-processor" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ibpb-on-vm-exit=on | off</option></term> + <listitem><para> + Enables use of Indirect Branch Prediction Barrier (IBPB) + on every VM exit. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ibpb-on-vm-entry=on | off</option></term> + <listitem><para> + Enables use of Indirect Branch Prediction Barrier (IBPB) + on every VM entry. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--spec-ctrl=on | off</option></term> + <listitem><para> + Enables or disables the exposure of speculation control + interfaces to the guest VM. These interfaces must be + available on the host system. + </para><para> + Depending on the host CPU and the workload, enabling + speculation control might significantly reduce + performance. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--l1d-flush-on-sched=on | off</option></term> + <listitem><para> + Enables or disables level 1 data cache flushing when a + thread is scheduled to execute guest code. See + <xref linkend="sec-rec-cve-2018-3646" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--l1d-flush-on-vm-entry=on | off</option></term> + <listitem><para> + Enables or disables level 1 data cache flushing on every + VM entry. See <xref linkend="sec-rec-cve-2018-3646" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mds-clear-on-sched=on | off</option></term> + <listitem><para> + Enables CPU buffer clearing when a thread is scheduled to + execute guest code. See + <xref linkend="sec-rec-cve-2018-12126-et-al" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mds-clear-on-vm-entry=on | off</option></term> + <listitem><para> + Enables CPU buffer clearing on every VM entry. See + <xref linkend="sec-rec-cve-2018-12126-et-al" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpu-profile=host | Intel 8086 | Intel 80286 | Intel 80386</option></term> + <listitem><para> + Specifies the profile to use for guest CPU emulation. + Specify a value that is based on the host system CPU + (<literal>host</literal>) or one of the following older + Intel micro-architectures: <literal>8086</literal>, + <literal>80286</literal>, or <literal>80386</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--hpet=on | off</option></term> + <listitem><para> + Enables or disables a High Precision Event Timer (HPET) + that can replace a legacy system timer. This feature is + disabled by default. Note HPET is supported on Windows + versions starting with Vista. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--hwvirtex=on | off</option></term> + <listitem><para> + Enables or disables the use of hardware virtualization + extensions in the processor of the host system. Such + extensions are Intel VT-x or AMD-V. See + <xref linkend="hwvirt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--triple-fault-reset=on | off</option></term> + <listitem><para> + Enables or disables the resetting of the guest VM instead + of triggering a Guru Meditation. Some guest VMs raise a + triple fault to reset the CPU, so sometimes resetting the + guest VM is the best outcome. This option only applies to + guests that do not use symmetric multiprocessing (SMP). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--apic=on | off</option></term> + <listitem><para> + Enables or disables APIC. With APIC, OSes can use + more than 16 interrupt requests (IRQs) to avoid IRQ + sharing and to improve reliability. APIC is enabled by + default. See <xref linkend="settings-motherboard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--x2apic=on | off</option></term> + <listitem><para> + Enables or disables the CPU x2APIC feature. CPU x2APIC + enables an OS to run more efficiently on high core count + configurations and to optimize interrupt distribution in + virtualized environments. This feature is enabled by + default. + </para><para> + Disable this feature when the OS that runs on a host + system or a guest VM is incompatible with CPU x2APIC. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--paravirt-provider=none | default | legacy | minimal | hyperv | kvm</option></term> + <listitem><para> + Specifies one of the following paravirtualization + interfaces to provide to the guest OS: + </para><itemizedlist> + <listitem><para> + <literal>none</literal> does not expose any + paravirtualization interface. + </para></listitem> + <listitem><para> + <literal>default</literal> selects the appropriate + interface based on the guest OS type when starting the + VM. This is the default value used when creating new + VMs. + </para></listitem> + <listitem><para> + <literal>legacy</literal> selects a paravirtual + interface for VMs that were created by older + &product-name; versions. + </para></listitem> + <listitem><para> + <literal>minimal</literal> is required for Mac OS X + guest VMs. + </para></listitem> + <listitem><para> + <literal>kvm</literal> is recommended for Linux guest + VMs. See <xref linkend="gimproviders" />. + </para></listitem> + <listitem><para> + <literal>hyperv</literal> is recommended for Windows + guest VMs. See <xref linkend="gimproviders" />. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--paravirt-debug=<replaceable>property</replaceable>=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies debugging properties that are specific to the + paravirtualization provider configured for the specified + VM. See <xref linkend="gimdebug" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nested-paging=on | off</option></term> + <listitem><para> + Enables or disables the nested paging feature in the + processor of the host system. This option is available + only when hardware virtualization is enabled. See + <xref linkend="hwvirt" /> and + <xref linkend="sec-rec-cve-2018-3646" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--large-pages=on | off</option></term> + <listitem><para> + Enables or disables the hypervisor's use of large pages, + which can improve performance by up to 5%. The use of + large pages reduces TLB use and overhead. This option is + available only when both hardware virtualization and + nested paging are enabled. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vtx-vpid=on | off</option></term> + <listitem><para> + Enables or disables the use of the tagged TLB (VPID) + feature in the processor of your host system. See + <xref linkend="hwvirt" />. This option is available only + when hardware virtualization is enabled on Intel VT-x. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vtx-ux=on | off</option></term> + <listitem><para> + Enables or disables the use of unrestricted guest mode for + executing the guest VM. This option is available only when + hardware virtualization is enabled on Intel VT-x. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nested-hw-virt=on | off</option></term> + <listitem><para> + Enables or disables nested virtualization. Enabling makes + hardware virtualization features available to the VM. See + <xref linkend="nested-virt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--virt-vmsave-vmload=on | off</option></term> + <listitem><para> + If hardware virtualization is enabled and the host has an + AMD CPU, this setting enables or disables the use of the + virtualized vmsave/vmload host feature while executing the + VM. It is enabled by default. It is recommended to leave it + enabled as it has a drastic impact on performance while + executing nested VMs when using the nested hardware + virtualization feature. + <xref linkend="nested-virt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--accelerated3d=on | off</option></term> + <listitem><para> + Enables or disables hardware 3D acceleration for the + graphics adapter variants which support it. This option + has an effect only when the Guest Additions are installed. + See <xref linkend="guestadd-3d" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--accelerated2dvideo=on | off</option></term> + <listitem><para> + Enables or disables 2D video acceleration for the graphics + adapter variants which support it. This option has an effect + only when the Guest Additions are installed. See + <xref linkend="guestadd-2d" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--chipset=piix3 | ich9</option></term> + <listitem><para> + Specify the Intel chipset for &product-name; to emulate. + The default value is the Intel PIIX3 chipset + (<literal>piix3</literal>). + </para><para> + Change this value only if you need to relax some of the + chipset constraints. See + <xref linkend="settings-motherboard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--iommu=none | automatic | amd | intel</option></term> + <listitem><para> + Specifies the IOMMU type for &product-name; to emulate. + Both Intel and AMD IOMMU emulation currently require the + use of the Intel ICH9 chipset (see + <option>--chipset</option> option). + </para><para> + Valid values are as follows: + </para><itemizedlist> + <listitem><para> + <literal>none</literal> – No IOMMU is present + and is the default value. + </para></listitem> + <listitem><para> + <literal>automatic</literal> – An IOMMU is + present but its type is automatically chosen to match + the host CPU vendor when the VM is powered on. + </para></listitem> + <listitem><para> + <literal>amd</literal> – An AMD IOMMU is + present. + </para></listitem> + <listitem><para> + <literal>intel</literal> – An Intel IOMMU is + present. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--tpm-type=none | 1.2 | 2.0 | host | swtpm</option></term> + <listitem><para> + Specifies the TPM type for &product-name; to emulate. + </para><para> + Valid values are as follows: + </para><itemizedlist> + <listitem><para> + <literal>none</literal> – No TPM is present + and is the default value. + </para></listitem> + <listitem><para> + <literal>1.2</literal> – A TPM conforming to the TCG specification + version 1.2 is present. + </para></listitem> + <listitem><para> + <literal>2.0</literal> – A TPM conforming to the TCG specification + version 2.0 is present. + </para></listitem> + <listitem><para> + <literal>host</literal> – The host TPM is passed through to the guest. + May not be available on all supported host platforms. + </para></listitem> + <listitem><para> + <literal>swtpm</literal> – The VM connects to an external TPM emulation + compliant to swtpm. Requires to set the TPM location to connect to (see + <option>--tpm-location</option> option). + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-logo-fade-in=on | off</option></term> + <listitem><para> + Specifies whether the BIOS logo fades in on VM startup. By + default, an &product-name; logo is shown. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-logo-fade-out=on | off</option></term> + <listitem><para> + Specifies whether the BIOS logo fades out on VM startup. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-logo-display-time=<replaceable>msec</replaceable></option></term> + <listitem><para> + Specifies the amount of time in milliseconds that the BIOS + logo is visible. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-logo-image-path=<replaceable>pathname</replaceable></option></term> + <listitem><para> + Replaces the existing BIOS logo with a different image. + The replacement image must be an uncompressed 16, 256 or 16M + color bitmap file (BMP) that does not contain color space + information (Windows 3.0 format). Also ensure that the + image is no larger than 640 X 480 pixels. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-boot-menu=disabled | menuonly | messageandmenu</option></term> + <listitem><para> + Specifies whether the BIOS permits you to select a + temporary boot device. Valid values are: + </para><itemizedlist> + <listitem><para> + <literal>disabled</literal> outputs the alternate boot + device message and permits you to select a temporary + boot device by pressing F12. + </para></listitem> + <listitem><para> + <literal>menuonly</literal> suppresses the alternate + boot device message, but permits you to select a + temporary boot device by pressing F12. + </para></listitem> + <listitem><para> + <literal>messageandmenu</literal> suppresses the + alternate boot device message and prevents you from + selecting a temporary boot device by pressing F12. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-apic=x2apic | apic | disabled</option></term> + <listitem><para> + Specifies the APIC level of the firmware. Valid values + are: <literal>x2apic</literal>, <literal>apic</literal>, + and <literal>disabled</literal>. When the value is + <literal>disabled</literal>, neither the + <literal>apic</literal> nor the <literal>x2apic</literal> + version of the firmware is used. + </para><para> + Note that if you specify the <literal>x2apic</literal> + value and x2APIC is unsupported by the virtual CPU, the + APIC level downgrades to <literal>apic</literal>, if + supported. Otherwise, the APIC level downgrades to + <literal>disabled</literal>. Similarly, if you specify the + <literal>apic</literal> value and APIC is unsupported by + the virtual CPU, the APIC level downgrades to + <literal>disabled</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-system-time-offset=<replaceable>msec</replaceable></option></term> + <listitem><para> + Specifies the time offset in milliseconds of the guest VM + relative to the time on the host system. If the offset + value is positive, the guest VM time runs ahead of the + time on the host system. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-pxe-debug=on | off</option></term> + <listitem><para> + Enables or disables additional debugging output when using + the Intel PXE boot ROM. The debug output is written to the + release log file. See + <xref linkend="collect-debug-info" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--system-uuid-le=on | off</option></term> + <listitem><para> + Enables or disables representing the system UUID in little + endian form. The default value is <literal>on</literal> for + new VMs. For old VMs the setting is <literal>off</literal> to + keep the content of the DMI/SMBIOS table unchanged, which can + be important for Windows license activation. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--boot<replaceable>N</replaceable>=none | floppy | dvd | disk | net</option></term> + <listitem><para> + Enables you to specify the boot device order for the VM by + assigning one of the device types to each of the four boot + device slots that are represented by + <replaceable>N</replaceable> in the option name. + </para><para> + A value of 1 for <replaceable>N</replaceable> represents + the first boot device slot, and so on. + </para><para> + The device types are <literal>floppy</literal> for floppy + disks, <literal>dvd</literal> for DVDs or CDs, + <literal>disk</literal> for hard disks, and + <literal>net</literal> for a network device. A value of + <literal>none</literal> indicates that no boot device is + associated with the specified slot. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--rtc-use-utc=on | off</option></term> + <listitem><para> + Specifies whether the real-time clock (RTC) uses + coordinated universal time (UTC). See + <xref linkend="settings-motherboard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--graphicscontroller=none | vboxvga | vmsvga | vboxsvga</option></term> + <listitem><para> + Specifies the graphics controller type to use. See + <xref linkend="settings-screen" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--snapshot-folder=default | <replaceable>pathname</replaceable></option></term> + <listitem><para> + Specifies the name of the VM's snapshot storage folder. If + you specify <literal>default</literal>, the folder name is + <filename>Snapshots/</filename> in the machine folder. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--firmware=bios | efi | efi32 | efi64</option></term> + <listitem><para> + Specifies the firmware used to boot the VM. Valid values + are: <literal>bios</literal>, <literal>efi</literal>, + <literal>efi32</literal>, or <literal>efi64</literal>. Use + EFI values with care. + </para><para> + By default, BIOS firmware is used. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--guest-memory-balloon=<replaceable>size</replaceable></option></term> + <listitem><para> + Specifies the size of the guest memory balloon. The guest + memory balloon is the memory allocated by the Guest + Additions from the guest OS and returned to the hypervisor + for use by other VMs. Specify + <replaceable>size</replaceable> in megabytes. The default + value is <literal>0</literal> megabytes. See + <xref linkend="guestadd-balloon" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--default-frontend=default | <replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the default frontend to use when starting the + specified VM. If you specify <literal>default</literal>, + the VM is shown in a window on the user's desktop. See + <xref linkend="vboxmanage-startvm" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vm-process-priority=default | flat | low | normal | high</option></term> + <listitem><para> + Specifies the priority scheme of the VM process to use + when starting the specified VM and while the VM runs. + </para><para> + The following valid values are: + </para><itemizedlist> + <listitem><para> + <literal>default</literal> – Default process + priority determined by the OS. + </para></listitem> + <listitem><para> + <literal>flat</literal> – Assumes a scheduling + policy which puts the process at the default priority + and with all threads at the same priority. + </para></listitem> + <listitem><para> + <literal>low</literal> – Assumes a scheduling + policy which puts the process mostly below the default + priority of the host OS. + </para></listitem> + <listitem><para> + <literal>normal</literal> – Assume a scheduling + policy which shares the CPU resources fairly with + other processes running with the default priority of + the host OS. + </para></listitem> + <listitem><para> + <literal>high</literal> – Assumes a scheduling + policy which puts the task above the default priority of + the host OS. This policy might easily cause other tasks + in the system to starve. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-networking"> + <title>Networking Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The following options enable you to modify networking on your + VM. With all these options, <replaceable>N</replaceable> is an + integer greater than zero that represents the particular virtual + network adapter to configure. + </para> + <variablelist> + <varlistentry> + <term><option>--nic<replaceable>N</replaceable>=none | null | nat | natnetwork | bridged | intnet | hostonly | generic</option></term> + <listitem><para> + Configures the network type used by each virtual network + card in the VM. + </para><para> + The following valid values correspond to the modes + described in <xref linkend="networkingmodes" />: + </para><itemizedlist> + <listitem><para> + <literal>none</literal> – No networking present + </para></listitem> + <listitem><para> + <literal>null</literal> – Not connected to the + host system + </para></listitem> + <listitem><para> + <literal>nat</literal> – Use network address + translation (NAT) + </para></listitem> + <listitem><para> + <literal>natnetwork</literal> – Use a NAT + network + </para></listitem> + <listitem><para> + <literal>bridged</literal> – Use bridged + networking + </para></listitem> + <listitem><para> + <literal>intnet</literal> – Use internal + networking + </para></listitem> + <listitem><para> + <literal>hostonly</literal> – Use host-only + networking + </para></listitem> + <listitem><para> + <literal>generic</literal> – Access rarely used + sub-modes + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-type<replaceable>N</replaceable>=Am79C970A | Am79C973 | 82540EM | 82543GC | 82545EM | virtio</option></term> + <listitem><para> + Identifies the type of networking hardware that + &product-name; presents to the guest VM for the specified + virtual network card. See <xref linkend="nichardware" />. + </para><para> + Valid values are as follows: + </para><itemizedlist> + <listitem><para> + <literal>Am79C970A</literal> represents the AMD PCNet + PCI II. + </para></listitem> + <listitem><para> + <literal>Am79C973</literal> represents the AMD PCNet + FAST III, which is the default value. + </para></listitem> + <listitem><para> + <literal>82540EM</literal> represents the Intel + PRO/1000 MT Desktop. + </para></listitem> + <listitem><para> + <literal>82543GC</literal> represents the Intel + PRO/1000 T Server. + </para></listitem> + <listitem><para> + <literal>82545EM</literal> represents the Intel + PRO/1000 MT Server. + </para></listitem> + <listitem><para> + <literal>virtio</literal> represents a paravirtualized + network adapter. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--cable-connected<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + Temporarily disconnects a virtual network interface, as if + you pull a network cable from a physical network card. You + might use this option to reset certain software components + in the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-trace<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + Enables or disables network tracing for the specified + virtual network card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-trace-file<replaceable>N</replaceable>=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies the absolute path of the file in which to write + trace log information. Use this option if network tracing + is enabled. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-property<replaceable>N</replaceable>=<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term> + <listitem><para> + Enables you to set property values and pass them to rarely + used network backends. To use this option, you must also + use the <option>--nic-generic-drv</option> option. + </para><para> + These properties are specific to the backend engine and + differ between the UDP Tunnel and the VDE backend drivers. + For property examples, see + <xref linkend="network_udp_tunnel" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-speed<replaceable>N</replaceable>=<replaceable>kbps</replaceable></option></term> + <listitem><para> + Specifies the throughput rate in kilobits per second for + rarely used networking sub-modes such as VDE network and + UDP Tunnel. Use this option only if you used the + <option>--nic</option> option to enable generic networking + for the specified virtual network card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-boot-prio<replaceable>N</replaceable>=<replaceable>priority</replaceable></option></term> + <listitem><para> + Assigns a priority to each NIC that determines the order + in which that NIC is used to perform a PXE network boot. + The priority value is an integer in the range from + <literal>0</literal> to <literal>4</literal>. Priority + <literal>0</literal>, which is the default value, is the + lowest priority. Priority <literal>1</literal> is the + highest priority, and priorities <literal>3</literal> and + <literal>4</literal> are lower. + </para><para> + This option has an effect only when using the Intel PXE + boot ROM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-promisc<replaceable>N</replaceable>=deny | allow-vms | allow-all</option></term> + <listitem><para> + Enables you to specify whether to deny or allow + promiscuous mode for the specified VM virtual network + card. This option is relevant only for bridged networking. + Valid values are as follows: + </para><itemizedlist> + <listitem><para> + <literal>deny</literal> hides any traffic that is not + intended for the VM. This is the default value. + </para></listitem> + <listitem><para> + <literal>allow-vms</literal> hides all host traffic + from the VM, but allows the VM to see traffic to and + from other VMs. + </para></listitem> + <listitem><para> + <literal>allow-all</literal> allows the VM to see all + traffic. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-bandwidth-group<replaceable>N</replaceable>=none | <replaceable>name</replaceable></option></term> + <listitem><para> + Adds or removes a bandwidth group assignment to the + specified virtual network interface. Valid values are as + follows: + </para><itemizedlist> + <listitem><para> + <literal>none</literal> removes any current bandwidth + group assignment from the specified virtual network + interface. + </para></listitem> + <listitem><para> + <replaceable>name</replaceable> adds a bandwidth group + assignment to the specified virtual network interface. + </para></listitem> + </itemizedlist><para> + See <xref linkend="network_bandwidth_limit" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bridge-adapter<replaceable>N</replaceable>=none | <replaceable>device-name</replaceable></option></term> + <listitem><para> + Specifies the host interface to use for the specified + virtual network interface. See + <xref linkend="network_bridged" />. Use this option only + if you used the <option>--nic</option> option to enable + bridged networking for the specified virtual network card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--host-only-adapter<replaceable>N</replaceable>=none | <replaceable>device-name</replaceable></option></term> + <listitem><para> + Specifies which host-only networking interface to use for + the specified virtual network interface. See + <xref linkend="network_hostonly" />. Use this option only + if you used the <option>--nic</option> option to enable + host-only networking for the specified virtual network + card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--intnet<replaceable>N</replaceable>=<replaceable>network-name</replaceable></option></term> + <listitem><para> + Specifies the name of the internal network. See + <xref linkend="network_internal" />. Use this option only + if you used the <option>--nic</option> option to enable + internal networking for the specified virtual network + card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-network<replaceable>N</replaceable>=<replaceable>network-name</replaceable></option></term> + <listitem><para> + Specifies the name of the NAT network to which this + adapter is connected. Use this option only if the + networking type is <literal>natnetwork</literal>, not + <literal>nat</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-generic-drv<replaceable>N</replaceable>=<replaceable>backend-driver</replaceable></option></term> + <listitem><para> + Enables you to access rarely used networking sub-modes, + such as VDE networks and UDP Tunnel. Use this option only + if you used the <option>--nic</option> option to enable + generic networking for a virtual network card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mac-address<replaceable>N</replaceable>=auto | <replaceable>MAC-address</replaceable></option></term> + <listitem><para> + Specifies the MAC address of the specified network adapter + on the VM. By default, &product-name; assigns a random MAC + address to each network adapter at VM creation. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-networking-nat"> + <title>NAT Networking Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The following options use <replaceable>N</replaceable> to + specify the particular virtual network adapter to modify. + </para> + <variablelist> + <varlistentry> + <term><option>--nat-net<replaceable>N</replaceable>=default | <replaceable>network</replaceable></option></term> + <listitem><para> + Specifies the IP address range to use for this network. + See <xref linkend="changenat" />. Use this option only if + the networking type is <literal>nat</literal>, not + <literal>natnetwork</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-pf<replaceable>N</replaceable>=[<replaceable>name</replaceable>],tcp | udp,[<replaceable>host-IP</replaceable>],<replaceable>hostport</replaceable>,[<replaceable>guest-IP</replaceable>],<replaceable>guestport</replaceable></option></term> + <listitem><para> + Specifies the NAT port-forwarding rule to use. See + <xref linkend="natforward" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-pf<replaceable>N</replaceable>=delete <replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the NAT port-forwarding rule to delete. See + <xref linkend="natforward" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-tftp-prefix<replaceable>N</replaceable>=<replaceable>prefix</replaceable></option></term> + <listitem><para> + Specifies a prefix to use for the built-in TFTP server. + For example, you might use a prefix to indicate where the + boot file is located. See <xref linkend="nat-tftp" /> and + <xref linkend="nat-adv-tftp" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-tftp-file<replaceable>N</replaceable>=<replaceable>boot-file</replaceable></option></term> + <listitem><para> + Specifies the name of the TFT boot file. See + <xref linkend="nat-adv-tftp" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-tftp-server<replaceable>N</replaceable>=<replaceable>tftp-server</replaceable></option></term> + <listitem><para> + Specifies the address of the TFTP server from which to + boot. See <xref linkend="nat-adv-tftp" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-bind-ip<replaceable>N</replaceable>=<replaceable>IP-address</replaceable></option></term> + <listitem><para> + Specifies an alternate IP address to which the NAT engine + binds. See <xref linkend="nat-adv-settings" />. By + default, &product-name;'s NAT engine routes TCP/IP packets + through the default interface assigned by the host's + TCP/IP stack. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-dns-pass-domain<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + Specifies whether the built-in DHCP server passes the + domain name for network name resolution. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-dns-proxy<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + Specifies whether the NAT engine is the proxy for all + guest DNS requests to the host system's DNS servers. See + <xref linkend="nat-adv-dns" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-dns-host-resolver<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + Specifies whether the NAT engine uses the host system's + resolver mechanisms to handle DNS requests. See + <xref linkend="nat-adv-dns" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-localhostreachable<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + Specifies whether the NAT engine allows traffic from the guest directed to + 10.0.2.2 to pass to the host's loopback interface, i.e. localhost or 127.0.0.1. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-settings<replaceable>N</replaceable>=[<replaceable>mtu</replaceable>],[<replaceable>socksnd</replaceable>],[<replaceable>sockrcv</replaceable>],[<replaceable>tcpsnd</replaceable>],[<replaceable>tcprcv</replaceable>]</option></term> + <listitem><para> + Specifies values for tuning NAT performance. See + <xref linkend="nat-adv-settings" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-alias-mode<replaceable>N</replaceable>=default | [log],[proxyonly],[sameports]</option></term> + <listitem><para> + Specifies the behavior of the NAT engine core as follows: + </para><itemizedlist> + <listitem><para> + <literal>log</literal> enables logging + </para></listitem> + <listitem><para> + <literal>proxyonly</literal> switches off aliasing + mode and makes NAT transparent + </para></listitem> + <listitem><para> + <literal>sameports</literal> enforces that the NAT + engine sends packets through the same port on which + they originated + </para></listitem> + <listitem><para> + <literal>default</literal> disables all aliasing modes + </para></listitem> + </itemizedlist><para> + For more information, see + <xref linkend="nat-adv-alias" />. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-other-hardware"> + <title>Other Hardware Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The following options enable you to configure other hardware, + such as the serial port, monitor, audio device, USB ports, and + the clipboard, and drag-and-drop features. + </para> + <variablelist> + <varlistentry> + <term><option>--mouse=ps2 | usb | usbtablet | usbmultitouch | usbmtscreenpluspad</option></term> + <listitem><para> + Specifies the mode of the mouse to use in the VM. Valid + values are: <literal>ps2</literal>, + <literal>usb</literal>, <literal>usbtablet</literal>, + <literal>usbmultitouch</literal> and + <literal>usbmtscreenpluspad</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--keyboard=ps2 | usb</option></term> + <listitem><para> + Specifies the mode of the keyboard to use in the VM. Valid + values are: <literal>ps2</literal> and + <literal>usb</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uart<replaceable>N</replaceable>=off | <replaceable>I/O-base</replaceable> <replaceable>IRQ</replaceable></option></term> + <listitem><para> + Configures virtual serial ports for the VM. + <replaceable>N</replaceable> represents the serial port to + modify. Valid values are <literal>off</literal> to disable + the port or an I/O base address and IRQ. For information + about the traditional COM port I/O base address and IRQ + values, see <xref linkend="serialports" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uart-mode<replaceable>N</replaceable>=<replaceable>mode</replaceable></option></term> + <listitem><para> + Specifies how &product-name; connects the specified + virtual serial port to the host system that runs the VM. + See <xref linkend="serialports" />. + </para><para> + Ensure that you first configure the virtual serial port by + using the + <option>--uart<replaceable>N</replaceable></option> + option. + </para><para> + Specify one of the following connection modes for each + port: + </para><itemizedlist> + <listitem><para> + <literal>disconnected</literal> indicates that even + though the serial port is shown to the guest VM, it is + not connected. This state is like a physical COM port + without a cable attached. + </para></listitem> + <listitem><para> + <literal>server</literal> + <replaceable>pipe-name</replaceable> creates the + specified named pipe or local domain socket on the + host system and connects the virtual serial device to + it. + </para><para> + On a Windows host system, + <replaceable>pipe-name</replaceable> is a named pipe + that has a name that uses the following form: + <literal>\\.\pipe\<replaceable>pipe-name</replaceable></literal>. + </para><para> + On a Linux host system, + <replaceable>pipe-name</replaceable> is a local domain + socket. + </para></listitem> + <listitem><para> + <literal>client</literal> + <replaceable>pipe-name</replaceable> connects the + virtual serial device to the specified named pipe or + local domain socket. + </para><para> + Note that the named pipe or local domain socket must + already exist. + </para></listitem> + <listitem><para> + <literal>tcpserver</literal> + <replaceable>port</replaceable> creates a TCP socket + with the specified TCP port on the host system and + connects the virtual serial device to it. + </para><para> + For UNIX-like systems, use ports over 1024 for + non-root users. + </para></listitem> + <listitem><para> + <literal>tcpclient</literal> + <replaceable>hostname</replaceable>:<replaceable>port</replaceable> + connects the virtual serial device to the TCP socket. + </para><para> + Note that the TCP socket must already exist. + </para></listitem> + <listitem><para> + <literal>file</literal> + <replaceable>filename</replaceable> redirects the + serial port output to the specified raw file. Ensure + that <replaceable>filename</replaceable> is the + absolute path of the file on the host system. + </para></listitem> + <listitem><para> + <replaceable>device-name</replaceable>: specifies the + device name of a physical hardware serial port on the + specified host system to which the virtual serial port + connects. + </para><para> + Use this mode to connect a physical serial port to a + VM. + </para><para> + On a Windows host system, the device name is a COM + port such as <literal>COM1</literal>. On a Linux host + system, the device name is similar to + <filename>/dev/ttyS0</filename>. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--uart-type<replaceable>N</replaceable>=<replaceable>UART-type</replaceable></option></term> + <listitem><para> + Configures the UART type for the specified virtual serial + port (<replaceable>N</replaceable>). Valid values are + <literal>16450</literal>, <literal>16550A</literal>, and + <literal>16750</literal>. The default value is + <literal>16550A</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--lpt-mode<replaceable>N</replaceable>=<replaceable>device-name</replaceable></option></term> + <listitem><para> + Specifies the device name of the parallel port to use. + </para><para> + For a Windows host system, use a device name such as + <command>lpt1</command>. For a Linux host system, use a + device name such as <filename>/dev/lp0</filename>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--lpt<replaceable>N</replaceable>=<replaceable>I/O-base</replaceable> <replaceable>IRQ</replaceable></option></term> + <listitem><para> + Specifies the I/O base address and IRQ of the parallel + port. + </para><para> + You can view the I/O base address and IRQ that the VM uses + for the parallel port in the Device Manager. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-controller=<replaceable>controller-type</replaceable></option></term> + <listitem><para> + Specifies the audio controller to be used with the VM. + Valid audio controller type values are: + <literal>ac97</literal>, <literal>hda</literal>, and + <literal>sb16</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-codec=<replaceable>codec-type</replaceable></option></term> + <listitem><para> + Specifies the audio codec to be used with the VM. Valid + audio codec type values are: <literal>stac9700</literal>, + <literal>ad1980</literal>, <literal>stac9221</literal>, + and <literal>sb16</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-driver=<replaceable>type</replaceable></option></term> + <listitem><para> + Specifies whether which audio driver (backend) to use. + <literal>none</literal>, <literal>default</literal>, + <literal>null</literal>, <literal>dsound</literal>, + <literal>was</literal>, <literal>oss</literal>, + <literal>alsa</literal>, <literal>pulse</literal>, and + <literal>coreaudio</literal>. + </para><para> + Note that the audio driver are dependent on the host + operating system. Use the <command>VBoxManage + modifyvm</command> command usage output to determine the + supported audio types for your host system. + </para> + <para> + For maximum interoperability between hosts, the default + audio driver can be used. The VM will then automatically select + the most appropriate audio driver for the current host available. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-enabled=on|off</option></term> + <listitem><para> + Specifies whether to enable or disable audio for the VM. + </para> + <para> + This option has precedence over the --audio-on and --audio-off + options, i.e. turning off audio via this option will turn off + both, input and output, audio. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-in=on|off</option></term> + <listitem><para> + Specifies whether to enable or disable audio capture from + the host system. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-out=on|off</option></term> + <listitem><para> + Specifies whether to enable or disable audio playback from + the guest VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--clipboard-mode=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies how to share the guest VM or host system OS's + clipboard with the host system or guest VM, respectively. + Valid values are: <literal>disabled</literal>, + <literal>hosttoguest</literal>, + <literal>guesttohost</literal>, and + <literal>bidirectional</literal>. See + <xref linkend="generalsettings" />. + </para><para> + The clipboard feature is available only if you have the + Guest Additions be installed in the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--drag-and-drop=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies how to use the drag and drop feature between the + host system and the VM. Valid values are: + <literal>disabled</literal>, + <literal>hosttoguest</literal>, + <literal>guesttohost</literal>, and + <literal>bidirectional</literal>. See + <xref linkend="guestadd-dnd" />. + </para><para> + The drag and drop feature is available only if you have + the Guest Additions be installed in the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--monitor-count=<replaceable>count</replaceable></option></term> + <listitem><para> + Enables you to configure multiple monitors. See + <xref linkend="settings-display" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--usb-ohci=on | off</option></term> + <listitem><para> + Enables or disables the VM's virtual USB 1.1 controller. + See <xref linkend="settings-usb" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--usb-ehci=on | off</option></term> + <listitem><para> + Enables or disables the VM's virtual USB 2.0 controller. + See <xref linkend="settings-usb" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--usb-xhci=on | off</option></term> + <listitem><para> + Enables or disables the VM's virtual USB 3.0 controller. + This is the most efficient option if the VM supports it. + See <xref linkend="settings-usb" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--usb-rename=<replaceable>old-name</replaceable> <replaceable>new-name</replaceable></option></term> + <listitem><para> + Rename's the VM's virtual USB controller from + <replaceable>old-name</replaceable> to + <replaceable>new-name</replaceable>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-recording"> + <title>Recording Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The following options enable you to modify settings for video + recording, audio recording, or both. + </para> + <variablelist> + <varlistentry> + <term><option>--recording=on | off</option></term> + <listitem><para> + Enables or disables the recording of a VM session into a + WebM or VP8 file. When set to <literal>on</literal>, + recording begins when the VM session starts. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-screens=all | none | <replaceable>screen-ID</replaceable>[,<replaceable>screen-ID</replaceable>...</option></term> + <listitem><para> + Enables you to specify the VM screens to record. The + recording for each screen is output to its own file. Valid + values are: <literal>all</literal>, which records all + screens, <literal>none</literal>, which records no + screens, or one or more specified screens. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-file=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies the name of the file in which to save the + recording. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-max-size=<replaceable>MB</replaceable></option></term> + <listitem><para> + Specifies the maximum size of the recorded video file in + megabytes. When the file reaches the specified size, + recording stops. If the value is <literal>0</literal>, + recording continues until you manually stop recording. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-max-time=<replaceable>seconds</replaceable></option></term> + <listitem><para> + Specifies the maximum amount of time to record in seconds. + When the specified time elapses, recording stops. If the + value is <literal>0</literal>, recording continues until + you manually stop recording. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-opts=<replaceable>keyword</replaceable>=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies additional video-recording properties as a + comma-separated property keyword-value list. For example, + <literal>foo=bar,a=b</literal>. + </para><para> + Only use this option if you are an advanced user. For + information about keywords, see the <citetitle>Oracle VM + VirtualBox Programming Guide and Reference</citetitle>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-video-fps=<replaceable>fps</replaceable></option></term> + <listitem><para> + Specifies the maximum number of video frames per second + (FPS) to record. The recording ignores any frames that + have a higher frequency. When you increase the FPS, fewer + frames are ignored but the recording and the size of the + recording file increases. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-video-rate=<replaceable>bit-rate</replaceable></option></term> + <listitem><para> + Specifies the bit rate of the video in kilobits per + second. When you increase the bit rate, the recording + appearance improves and the size of the recording file + increases. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-video-res=<replaceable>width</replaceable>x<replaceable>height</replaceable></option></term> + <listitem><para> + Specifies the video resolution (width and height) of the + recorded video in pixels. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-vrde"> + <title>Remote Machine Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The following options enable you to modify the VirtualBox Remote + Desktop Extension (VRDE) behavior. + </para> + <variablelist> + <varlistentry> + <term><option>--vrde=on | off</option></term> + <listitem><para> + Enables or disables the VRDE server. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=TCP/Ports=<replaceable>port</replaceable></option></term> + <listitem><para> + <replaceable>port</replaceable> is the port or port range + to which the VRDE server binds. The + <literal>default</literal> or <literal>0</literal> value + uses port <literal>3389</literal>, which is the standard + RDP port. + </para><para> + Also see the <option>--vrde-port</option> option + description. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=TCP/Address=<replaceable>IP-address</replaceable></option></term> + <listitem><para> + <replaceable>IP-address</replaceable> is the IP address of + the host network interface to which the VRDE server binds. + When specified, the server accepts connections only on the + host network interface at that IP address. + </para><para> + Also see the <option>--vrde-address</option> option + description. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=VideoChannel/Enabled=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies whether the VRDP video channel is on or off. + <literal>1</literal> means <literal>on</literal> and + <literal>0</literal> means <literal>off</literal>. See + <xref linkend="vrde-videochannel" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=Quality=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies a value between 10% and 100%, inclusive, that + represents the JPEG compression level on the VRDE server + video channel. A lower value produces lower JPEG quality + but higher compression. See + <xref linkend="vrde-videochannel" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=DownscaleProtection=<replaceable>value</replaceable></option></term> + <listitem><para> + Enables or disables the video downscale protection + feature. Valid values are <literal>1</literal> to enable + the feature and <literal>0</literal> to disable the + feature. + </para><para> + When this feature is enabled, &product-name; determines + whether to display the video: + </para><itemizedlist> + <listitem><para> + When the video size equals the size of the shadow + buffer, the video is considered to be full screen and + is displayed. + </para></listitem> + <listitem><para> + When the video size is between full screen and the + downscale threshold, the video is not displayed. Such + a video might be an application window, which is + unreadable when downscaled. + </para></listitem> + </itemizedlist><para> + When this feature is disabled, an attempt is always made + to display a video. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=Client/DisableDisplay=1</option></term> + <listitem><para> + Disables the display VRDE server feature. + </para><para> + To reenable a feature, assign an empty value. For example, + to reenable the display feature, specify the + <command>VBoxManage modifyvm + --vrde-property=Client/DisableDisplay=</command> command. + See <xref linkend="vrde-customization" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=DisableInput=1</option></term> + <listitem><para> + Disables the input VRDE server feature. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=DisableAudio=1</option></term> + <listitem><para> + Disables the audio VRDE server feature. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=DisableUSB=1</option></term> + <listitem><para> + Disables the USB VRDE server feature. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=Client/DisableClipboard=1</option></term> + <listitem><para> + Disables the clipboard VRDE server feature. To reenable + the feature, assign an empty value. See + <xref linkend="vrde-customization" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=DisableUpstreamAudio=1</option></term> + <listitem><para> + Disables the upstream audio VRDE server feature. To + reenable the feature, assign an empty value. See + <xref linkend="vrde-customization" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=Client/DisableRDPDR=1</option></term> + <listitem><para> + Disables the RDP device redirection for smart cards VRDE + server feature. To reenable this feature, assign an empty + value. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=H3DRedirect/Enabled=1</option></term> + <listitem><para> + Enables the 3D redirection VRDE server feature. To disable + this feature, assign an empty value. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=Security/Method=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies the following information that is required for a + connection: + </para><itemizedlist> + <listitem><para> + <literal>Negotiate</literal> indicates that both + Enhanced (TLS) and Standard RDP Security connections + are permitted. The security method is negotiated with + the client. This is the default value. + </para></listitem> + <listitem><para> + <literal>RDP</literal> indicates that only Standard + RDP Security is accepted. + </para></listitem> + <listitem><para> + <literal>TLS</literal> indicates that only Enhanced + RDP Security is accepted. The client must support TLS. + </para></listitem> + </itemizedlist><para> + See <xref linkend="vrde-crypt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=ServerCertificate=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies the absolute path to the server certificate. See + <xref linkend="vrde-crypt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=ServerPrivateKey=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies the absolute path to the server private key. See + <xref linkend="vrde-crypt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=CACertificate=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies the absolute path to the CA self-signed + certificate. See <xref linkend="vrde-crypt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property Audio/RateCorrectionMode=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies the audio connection mode or the path to the + audio log file. Valid values are as follows: + </para><itemizedlist> + <listitem><para> + <literal>VRDP_AUDIO_MODE_VOID</literal> is no mode. + Use this value to unset any set audio mode. + </para></listitem> + <listitem><para> + <literal>VRDP_AUDIO_MODE_RC</literal> is the rate + correction mode. + </para></listitem> + <listitem><para> + <literal>VRDP_AUDIO_MODE_LPF</literal> is the low pass + filter mode. + </para></listitem> + <listitem><para> + <literal>VRDP_AUDIO_MODE_CS</literal> is the client + sync sync mode to prevent an underflow or overflow of + the client queue. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=LogPath=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies the absolute path to the audio log file. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-extpack=default | <replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the library to use to access the VM remotely. + The <literal>default</literal> value uses the RDP code + that is part of the &product-name; Extension Pack. + </para><para> + To use the VRDE module in VNC, specify + <literal>VNC</literal>. See + <xref linkend="otherextpacks"/>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-port=default | <replaceable>port</replaceable></option></term> + <listitem><para> + <replaceable>port</replaceable> is the port or port range + to which the VRDE server binds. The + <literal>default</literal> or <literal>0</literal> value + uses port <literal>3389</literal>, which is the standard + RDP port. + </para><para> + You can specify a comma-separated list of ports or port + ranges of ports. Use a dash between two port numbers to + specify a port range. The VRDE server binds to only one of + the available ports from the list. Only one machine can + use a given port at a time. For example, the + <option>--vrde-port=5000,5010-5012</option> option + specifies that server can bind to one of following ports: + <literal>5000</literal>, <literal>5010</literal>, + <literal>5011</literal>, or <literal>5012</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-address=<replaceable>IP-address</replaceable></option></term> + <listitem><para> + Specifies the IP address of the host network interface to + which the VRDE server binds. If you specify an IP address, + the server accepts connections only on the specified host + network interface. + </para><para> + Use this option to specify whether the VRDP server should + accept IPv4, IPv6, or both type of connections: + </para><itemizedlist> + <listitem><para> + <emphasis role="bold">Only IPv4:</emphasis> Use the + <option>--vrde-address="0.0.0.0"</option> option. + </para></listitem> + <listitem><para> + <emphasis role="bold">Only IPv6:</emphasis> Use the + <option>--vrde-address="::"</option> option. + </para></listitem> + <listitem><para> + <emphasis role="bold">Both IPv6 and IPv4:</emphasis> + Use the <option>--vrde-address=""</option> + option. This is the default value. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-auth-type=null | external | guest</option></term> + <listitem><para> + Specify whether to use authorization and how to perform + authorization. See <xref linkend="vbox-auth" />. Valid + values are as follows: + </para><itemizedlist> + <listitem><para> + <literal>null</literal> provides no authentication. + </para></listitem> + <listitem><para> + <literal>external</literal> provides external + authentication through an authentication library. + </para></listitem> + <listitem><para> + <literal>guest</literal> performs authentication by + using guest user accounts. This unsupported method + requires that you install the Guest Additions on the + VM. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-auth-library=default | <replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the library to use for RDP authentication. The + default library for external authentication is + <filename>VBoxAuth</filename>. See + <xref linkend="vbox-auth" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-multi-con=on | off</option></term> + <listitem><para> + Enables or disables the multiple connections VRDE server + feature, if supported. See + <xref linkend="vrde-multiconnection" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-reuse-con=on | off</option></term> + <listitem><para> + Specifies how the VRDE server behaves when multiple + connections are disabled. When the value is + <literal>on</literal>, the server permits a new client to + connect and drops the existing connection. When the value + is <literal>off</literal>, a new connection is not + accepted if a client is already connected to the server. + This is the default value. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-video-channel=on | off</option></term> + <listitem><para> + Enables video redirection if supported by the VRDE server. + See <xref linkend="vrde-videochannel" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-video-channel-quality=<replaceable>percent</replaceable></option></term> + <listitem><para> + Specifies the image quality for video redirection as a + value from 10 to 100 percent. The percentage represents + the JPEG compression level where a lower number diminishes + quality and provides higher compression. See + <xref linkend="vrde-videochannel" />. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-teleport"> + <title>Teleporting Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The following options enable you to configure a machine as a + teleporting target. See <xref linkend="teleporting" /> and the + teleporting related entries in <xref linkend="pot-insecure" />. + </para> + <variablelist> + <varlistentry> + <term><option>--teleporter=on | off</option></term> + <listitem><para> + Enables or disables the teleporter. When enabled, a + machine starts up and waits to receive a teleporting + request from the network instead of booting normally. + </para><para> + Teleporting requests are received on the port and address + specified using the following parameters. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--teleporter-port=<replaceable>port</replaceable></option></term> + <listitem><para> + Specifies the port on which the VM listens to receive a + teleporting request from another VM. + <replaceable>port</replaceable> is any free TCP/IP port + number, such as <literal>6000</literal>. You must also + specify the <option>--teleporter</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--teleporter-address=<replaceable>IP-address</replaceable></option></term> + <listitem><para> + Specifies the IP address on which the VM listens to + receive a teleporting request from another VM. + <replaceable>IP-address</replaceable> is any IP address or + host name and specifies the TCP/IP socket on which to + bind. The default IP address is + <literal>0.0.0.0</literal>, which represents any IP + address. You must also specify the + <option>--teleporter</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--teleporter-password=<replaceable>password</replaceable></option></term> + <listitem><para> + Specifies the password to use for authentication. When + specified, the teleporting request only succeeds if the + password on the source machine is the same password as the + one you specify. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--teleporter-password-file=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies a file that contains the password to use for + authentication. When specified, the teleporting request + only succeeds if the password on the source machine is the + same password as the one you specify in the password file. + A value of <literal>stdin</literal> reads the password + from standard input. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpuid-portability-level=<replaceable>level</replaceable></option></term> + <listitem> + <para> + Restricts the virtual CPU capabilities that &product-name; + presents to the guest OS by using portability rules. Higher + integer values designate more restrictive behavior. The + default level of <literal>0</literal> indicates that all + virtualized features supported by the host are made available + to the guest. The value <literal>3</literal> supresses most + features. Values of <literal>1</literal> and <literal>2</literal> + represent restrictions in between. The behavior may change + depending on the product version. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpuid-set=<replaceable>leaf</replaceable>[:<replaceable>subleaf</replaceable>] + <replaceable>eax</replaceable> <replaceable>ebx</replaceable> <replaceable>ecx</replaceable> <replaceable>edx</replaceable></option></term> + <listitem> + <para> + Advanced users can use this setting before a teleporting + operation (in fact before starting the VM) to restrict the + virtual CPU capabilities that &product-name; presents to + the guest operating system. This must be run on both the + source and the target machines involved in teleporting and + will then modify what the guest sees when it executes the + CPUID machine instruction. This might help with misbehaving + applications that wrongly assume that certain CPU + capabilities are present. The meaning of the parameters + is hardware dependent. Refer to the AMD or Intel processor + documentation. + </para><para> + The values of <replaceable>leaf</replaceable>, + <replaceable>subleaf</replaceable> (optional), + <replaceable>eax</replaceable>, <replaceable>ebx</replaceable>, + <replaceable>ecx</replaceable> and <replaceable>edx</replaceable> + are integers given in hexadecimal format, i.e. using a radix + (base) of 16 without requiring any prefix. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpuid-remove=<replaceable>leaf</replaceable>[:<replaceable>subleaf</replaceable>]</option></term> + <listitem> + <para> + Removes an adjustment established with <option>--cpuid-set</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpuid-remove-all</option></term> + <listitem> + <para> + Removes all adjustments established with <option>--cpuid-set</option>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-debugging"> + <title>Debugging Settings</title> + <remark role="help-copy-synopsis"/> + <para> + Only use the following options to perform low-level VM + debugging. These options are for advanced users only. + </para> + <variablelist> + <varlistentry> + <term><option>--tracing-enabled=on | off</option></term> + <listitem><para> + Enables or disables the trace buffer. Note that when + specified, the trace buffer consumes some memory and adds + overhead. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tracing-config=<replaceable>config-string</replaceable></option></term> + <listitem><para> + Enables a tracing configuration that defines which group + of trace points are enabled. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tracing-allow-vm-access=on | off</option></term> + <listitem><para> + Enables or disables VM access to the trace buffer. The + default value is <literal>off</literal>, which disables + access. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-usbcardreader"> + <title>USB Card Reader Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The following options specify the access to a USB Card Reader by + the guest environment. A USB card reader can access data on + memory cards, such as CompactFlash (CF), Secure Digital (SD), + and MultiMediaCard (MMC). + </para> + <variablelist> + <varlistentry> + <term><option>--usb-card-reader=on | off</option></term> + <listitem><para> + Enables or disables the USB card reader interface. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-autostart"> + <title>Autostarting VMs During Host System Boot</title> + <para> + The following options enable you to configure the VM autostart + feature, which automatically starts the VM at host system + boot-up. You must do some host system configuration before you + can use this feature. See <xref linkend="autostart" />. + </para> + <remark role="help-copy-synopsis"/> + <variablelist> + <varlistentry> + <term><option>--autostart-enabled=on | off</option></term> + <listitem><para> + Enables or disables VM autostart at host system boot-up + for the specified users. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--autostart-delay=<replaceable>seconds</replaceable></option></term> + <listitem><para> + Specifies the number of seconds after host system boot-up + to autostart the VM. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-guest-debug"> + <title>Guest Debugging</title> + <para> + These options are for configuring the VMM for guest debugging. + </para> + <remark role="help-copy-synopsis"/> + <variablelist> + <varlistentry> + <term><option>--guest-debug-provider=none | native | gdb | kd</option></term> + <listitem><para>Selects the given debug stub provider. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--guest-debug-io-provider=none | tcp | udp | ipc</option></term> + <listitem><para>Selects the given I/O transport backend for the selected provider.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--guest-debug-address=<replaceable>IP-Address</replaceable> | <replaceable>path</replaceable></option></term> + <listitem><para>Sets the path the debugger is accessible under, depends on the selected I/O transport.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--guest-debug-port=<replaceable>port</replaceable></option></term> + <listitem><para>Sets the port the debugger is accessible under, depends on the selected I/O transport.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-pcipassthrough"> + <title>PCI Passthrough Settings</title> + <para> + The following options enable you to configure the PCI passthrough + feature, which currently is not available in &product-name;. It is + planned to bring this functionality back in the future. + </para> + <remark role="help-copy-synopsis"/> + <variablelist> + <varlistentry> + <term><option>--pci-attach=<replaceable>host-PCI-address</replaceable>[@<replaceable>guest-PCI-bus-address</replaceable>]</option></term> + <listitem><para> + Attaches the specified PCI network controller on the host + to the guest VM. You can optionally specify the PCI bus on + the guest VM on which to attach the controller. +<!-- See <xref linkend="pcipassthrough" />. --> + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--pci-detach=<replaceable>host-PCI-address</replaceable></option></term> + <listitem><para> + Detaches the specified PCI network controller from the + attached PCI bus on the guest VM. +<!-- See <xref linkend="pcipassthrough" />. --> + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-testing"> + <title>Testing (ValidationKit / Bootsector)</title> + <para> + These options are for configuring the testing functionality of the VMM + device and almost exclusively used by the bootsector testcases in the + ValidationKit. + </para> + <remark role="help-copy-synopsis"/> + <variablelist> + <varlistentry> + <term><option>--testing-enabled=on | off</option></term> + <listitem><para>Enabled the testing functionality of the VMMDev. See VMMDevTesting.h for details. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--testing-mmio=on | off</option></term> + <listitem><para>Enabled the MMIO region of the VMMDev testing feature.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--testing-cfg-dword<replaceable>idx</replaceable>=<replaceable>value</replaceable></option></term> + <listitem><para> + This sets one of the 10 dword configuration values. The + <replaceable>idx</replaceable> must be in the range 0 thru 9. + The <replaceable>value</replaceable> is limited to 32 bits (dword). + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command changes the description for the + <filename>ol7</filename> VM. + </para> +<screen>$ VBoxManage modifyvm ol7 --description "Oracle Linux 7 with UEK4"</screen> + <para> + The following command enables VirtualBox Remote Display Protocol + (VRDP) support for the <filename>ol7</filename> VM. + </para> +<screen>$ VBoxManage modifyvm ol7 --vrde on</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-showvminfo" />, + <xref linkend="vboxmanage-controlvm" />, + <xref linkend="vboxmanage-createvm" />, + <xref linkend="vboxmanage-startvm" /> + <xref linkend="vboxmanage-list" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-movevm.xml b/doc/manual/en_US/man_VBoxManage-movevm.xml new file mode 100644 index 00000000..c0afc329 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-movevm.xml @@ -0,0 +1,113 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage movevm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-movevm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage movevm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-movevm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-movevm</refname> + <refpurpose>move a virtual machine to a new location on the host system</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-movevm"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage movevm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--type=basic</arg> + <arg>--folder=<replaceable>folder-name</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage movevm</command> command moves a virtual + machine (VM) to a new location on the host system. + </para> + <para> + When moved, all of the files that are associated with the VM, such + as settings files and disk image files, are moved to the new + location. The &product-name; configuration is updated + automatically. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or name + of the VM to move. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--type=basic</option></term> + <listitem><para> + Specifies the type of the move operation. So far + <literal>basic</literal> is the only recognized value and also + the default if not specified. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--folder=<replaceable>folder-name</replaceable></option></term> + <listitem><para> + Specifies a full path name or relative path name of the new + location on the host file system. Not specifying the option + or specifying the current location is allowed, and moves + disk images and other parts of the VM to this location if + they are currently in other locations. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command moves the <filename>ol7</filename> VM to a + new location on the host system. + </para> +<screen>$ VBoxManage movevm ol7 --folder "/home/testuser/vms" --type basic +0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100% +Machine has been successfully moved into /home/testuser/vms</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-natnetwork.xml b/doc/manual/en_US/man_VBoxManage-natnetwork.xml new file mode 100644 index 00000000..118cf746 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-natnetwork.xml @@ -0,0 +1,371 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage natnetwork +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-natnetwork" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage natnetwork</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-natnetwork</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-natnetwork</refname> + <refpurpose>create, modify, and manage a NAT network</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-natnetwork-add"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage natnetwork add</command> + <group> + <arg choice="plain">--disable</arg> + <arg choice="plain">--enable</arg> + </group> + <arg choice="req">--netname=<replaceable>name</replaceable></arg> + <arg choice="req">--network=<replaceable>network</replaceable></arg> + <arg>--dhcp=on|off</arg> + <arg>--ipv6=on|off</arg> + <arg>--loopback-4=<replaceable>rule</replaceable></arg> + <arg>--loopback-6=<replaceable>rule</replaceable></arg> + <arg>--port-forward-4=<replaceable>rule</replaceable></arg> + <arg>--port-forward-6=<replaceable>rule</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-natnetwork-list"> + <command>VBoxManage natnetwork list</command> + <arg><replaceable>filter-pattern</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-natnetwork-modify"> + <command>VBoxManage natnetwork modify</command> + <arg>--dhcp=on|off</arg> + <group> + <arg choice="plain">--disable</arg> + <arg choice="plain">--enable</arg> + </group> + <arg choice="req">--netname=<replaceable>name</replaceable></arg> + <arg choice="req">--network=<replaceable>network</replaceable></arg> + <arg>--ipv6=on|off</arg> + <arg>--loopback-4=<replaceable>rule</replaceable></arg> + <arg>--loopback-6=<replaceable>rule</replaceable></arg> + <arg>--port-forward-4=<replaceable>rule</replaceable></arg> + <arg>--port-forward-6=<replaceable>rule</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-natnetwork-remove"> + <command>VBoxManage natnetwork remove</command> + <arg choice="req">--netname=<replaceable>name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-natnetwork-start"> + <command>VBoxManage natnetwork start</command> + <arg choice="req">--netname=<replaceable>name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-natnetwork-stop"> + <command>VBoxManage natnetwork stop</command> + <arg choice="req">--netname=<replaceable>name</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage natnetwork</command> command enables you + to create, modify and manage a NAT network. + </para> + <para> + NAT networks use the Network Address Translation (NAT) service. + The service groups systems into a network and prevents external + systems from directly accessing the systems in the network. The + service also enables the systems in the network to communicate + with each other and with external systems by means of TCP and UDP + over IPv4 and IPv6. + </para> + <para> + A NAT service is attached to an internal network. For a VM to use + the NAT service, you must attach the VM to the internal network. + Specify the name of the internal network when you create the NAT + service. Note that the internal network is created if it does not + already exist. + </para> + <refsect2 id="vboxmanage-natnetwork-add"> + <title>Add a NAT Network Service</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage natnetwork add</command> command creates + a new internal network interface, and adds a NAT network + service. You must use this command before you can attach the VM + to the NAT network. + </para> + <variablelist> + <varlistentry> + <term><option>--disable</option></term> + <listitem><para> + Disables the NAT network service. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--enable</option></term> + <listitem><para> + Enables the NAT network service. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--netname=<replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the name of the new internal network interface + on the host OS. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--network</option></term> + <listitem><para> + Specifies the static or DHCP network address and mask of + the NAT service interface. By default, this value + specifies the static network address. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dhcp</option></term> + <listitem><para> + Enables or disables the DHCP server that you specify by + using the <option>--netname</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ipv6</option></term> + <listitem><para> + Enables or disables IPv6. By default, IPv6 is disabled and + IPv4 is enabled. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--loopback-4=<replaceable>rule</replaceable></option></term> + <listitem><para> + Enables an IPv4 loopback interface by using the specified + rule. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--loopback-6=<replaceable>rule</replaceable></option></term> + <listitem><para> + Enables an IPv6 loopback interface by using the specified + rule. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--port-forward-4=<replaceable>rule</replaceable></option></term> + <listitem><para> + Enables IPv4 port forwarding by using the rule specified + by <replaceable>rule</replaceable>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--port-forward-6=<replaceable>rule</replaceable></option></term> + <listitem><para> + Enables IPv6 port forwarding by using the rule specified + by <replaceable>rule</replaceable>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-natnetwork-remove"> + <title>Remove a NAT Network Service</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage natnetwork remove</command> command + removes the specified NAT network service. + </para> + <variablelist> + <varlistentry> + <term><option>--netname=<replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the name of the NAT network service to remove. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-natnetwork-start"> + <title>Start a NAT Network Service</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage natnetwork start</command> command + starts a NAT network service and any associated DHCP server. + </para> + <variablelist> + <varlistentry> + <term><option>--netname=<replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the name of the NAT network service to start. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-natnetwork-stop"> + <title>Stop a NAT Network Service</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage natnetwork stop</command> command stops + a NAT network service and any associated DHCP server. + </para> + <variablelist> + <varlistentry> + <term><option>--netname=<replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the name of the NAT network service to stop. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-natnetwork-list"> + <title>List All NAT Network Services</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage natnetwork list</command> command lists + all NAT network services. You can use a pattern to show a subset + of the NAT network services. + </para> + <variablelist> + <varlistentry> + <term><replaceable>filter-pattern</replaceable></term> + <listitem><para> + Specifies an optional filtering pattern. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-natnetwork-modify"> + <title>Modify the Settings of a NAT Network Service</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage natnetwork modify</command> command + modifies the settings of an existing internal network interface. + </para> + <variablelist> + <varlistentry> + <term><option>--disable</option></term> + <listitem><para> + Disables the NAT network service. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--enable</option></term> + <listitem><para> + Enables the NAT network service. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--netname=<replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the name of the new internal network interface + on the host OS. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--network</option></term> + <listitem><para> + Specifies the static or DHCP network address and mask of + the NAT service interface. By default, this value + specifies the static network address. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dhcp</option></term> + <listitem><para> + Enables or disables the DHCP server that you specify by + using the <option>--netname</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ipv6</option></term> + <listitem><para> + Enables or disables IPv6. By default, IPv6 is disabled and + IPv4 is enabled. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--loopback-4=<replaceable>rule</replaceable></option></term> + <listitem><para> + Enables an IPv4 loopback interface by using the specified + rule. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--loopback-6=<replaceable>rule</replaceable></option></term> + <listitem><para> + Enables an IPv6 loopback interface by using the specified + rule. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--port-forward-4=<replaceable>rule</replaceable></option></term> + <listitem><para> + Enables IPv4 port forwarding by using the rule specified + by <replaceable>rule</replaceable>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--port-forward-6=<replaceable>rule</replaceable></option></term> + <listitem><para> + Enables IPv6 port forwarding by using the rule specified + by <replaceable>rule</replaceable>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following command shows how to create a NAT network for the + <literal>natnet1</literal> internal network that uses the + <literal>192.168.15.0/24</literal> network address and mask of the + NAT service interface. In this static configuration, the gateway + is assigned the <literal>192.168.15.1</literal> IP address by + default. Note that this IP address is the next address after the + network address that you specify with the + <option>--network</option> option. + </para> +<screen>$ VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable</screen> + <para> + The following command shows how to add a DHCP server to the + <literal>natnet1</literal> NAT network after creation: + </para> +<screen>$ VBoxManage natnetwork modify --netname natnet1 --dhcp on</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-registervm.xml b/doc/manual/en_US/man_VBoxManage-registervm.xml new file mode 100644 index 00000000..af4c4d3e --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-registervm.xml @@ -0,0 +1,114 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage registervm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-registervm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage registervm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-registervm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-registervm</refname> + <refpurpose>register a virtual machine</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-registervm"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage registervm</command> + <arg choice="req"><replaceable>filename</replaceable></arg> + <arg choice="plain">--password <replaceable>file</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage registervm</command> command enables you + to create a virtual machine (VM) by importing an XML machine + configuration file into &product-name;. The VM cannot have the + same UUID as a VM that is already registered in &product-name;. + Ensure that the XML machine configuration file is in the machines + folder prior to registration. + </para> + <note> + <para> + When you use the <command>VBoxManage createvm</command> command + to create a VM, you can specify the <option>--register</option> + option to register the VM. + </para> + </note> + <variablelist> + <varlistentry> + <term><replaceable>filename</replaceable></term> + <listitem><para> + Specifies the XML machine configuration file. This file has + the <filename>.vbox</filename> file extension. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password</option></term> + <listitem> + <para> + Use the <option>--password</option> to supply the encryption + password of the VM. Either specify the absolute pathname of a + password file on the host operating system, or <literal>-</literal> + to prompt you for the password on the command line. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command registers a VM called + <literal>vm2</literal>. The XML machine configuration file for the + VM is located in the default machines folder. + </para> +<screen>$ VBoxManage registervm "/home/user/VirtualBox VMs/vm2/vm2.vbox"</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-createvm"/>, + <xref linkend="vboxmanage-unregistervm" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-setextradata.xml b/doc/manual/en_US/man_VBoxManage-setextradata.xml new file mode 100644 index 00000000..7327f5eb --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-setextradata.xml @@ -0,0 +1,123 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage setextradata +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-setextradata" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage setextradata</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-setextradata</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-setextradata</refname> + <refpurpose>set a keyword value that is associated with a virtual machine or + configuration</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-setextradata"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage setextradata</command> + <group choice="req"> + <arg choice="plain">global</arg> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="req"><replaceable>keyword</replaceable></arg> + <arg><replaceable>value</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage setextradata</command> command enables you + to set a keyword value that is associated with a virtual machine + (VM) or with an &product-name; configuration. + </para> + <variablelist> + <varlistentry> + <term><literal>global</literal></term> + <listitem><para> + Sets information about the configuration rather than a VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or name + of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>keyword</replaceable></term> + <listitem><para> + Specifies the keyword for which to set its value. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>value</replaceable></term> + <listitem><para> + Specifies the keyword value. Specifying no value removes the + keyword. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following command sets the <literal>installdate</literal> + keyword value for the <literal>Fedora5</literal> VM to + <literal>2019.01.01</literal>: + </para> +<screen>$ VBoxManage setextradata Fedora5 installdate 2019.01.01</screen> + <para> + The following command unsets the value of the + <literal>installdate</literal> keyword for the + <literal>Fedora5</literal> VM: + </para> +<screen>$ VBoxManage setextradata Fedora5 installdate</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-getextradata" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-setproperty.xml b/doc/manual/en_US/man_VBoxManage-setproperty.xml new file mode 100644 index 00000000..731edf2a --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-setproperty.xml @@ -0,0 +1,230 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage setproperty +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-setproperty" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage setproperty</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-setproperty</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-setproperty</refname> + <refpurpose>change global settings</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <cmdsynopsis id="synopsis-vboxmanage-setproperty"> + <command>VBoxManage setproperty</command> + <arg choice="req"><replaceable>property-name</replaceable></arg> + <arg choice="req"><replaceable>property-value</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage setproperty</command> command enables you + to change global settings that affect the entire &product-name; + installation. Some of these settings correspond to the settings in + the <emphasis role="bold">Preferences</emphasis> dialog in the + VirtualBox Manager. + </para> + <para> + The following properties are available: + </para> + <variablelist> + <varlistentry> + <term><literal>autostartdbpath</literal></term> + <listitem><para> + Specifies the path to the autostart database. Valid values + are <literal>null</literal>, which disables the autostart + database, or the name of the folder that contains the + database. See <xref linkend="autostart" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>defaultfrontend</literal></term> + <listitem><para> + Specifies the global default VM frontend. Valid values are + <literal>default</literal>, which specifies the default + frontend, or the name of the frontend to use. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>hwvirtexclusive</literal></term> + <listitem><para> + Specifies whether &product-name; makes exclusive use of the + Intel VT-x or AMD-V hardware virtualization extensions of + the host system's processor. See <xref linkend="hwvirt" />. + </para><para> + Valid values are as follows: + </para><itemizedlist> + <listitem><para> + <literal>on</literal> enables &product-name; to make + exclusive use of these extensions. This is the default + value. + </para></listitem> + <listitem><para> + <literal>off</literal> shares these extensions with + other hypervisors that run simultaneously. Note that + disabling this setting has negative performance + implications. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><literal>language</literal></term> + <listitem><para> + Specifies the user language used to translate API messages. + Valid values are <literal>C</literal>, which means no + translation or language code in form either <literal>ll</literal> + or <literal>ll_CC</literal>, where <literal>ll</literal> is + language 2 letters code in lower case and + <literal>CC</literal> is country 2 letter code in upper case. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>logginglevel</literal></term> + <listitem><para> + Specifies the VBoxSVC release logging details. See + <ulink url="http://www.virtualbox.org/wiki/VBoxLogging" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>loghistorycount</literal></term> + <listitem><para> + Specifies the number of rotated VM logs to retain. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>machinefolder</literal></term> + <listitem><para> + Specifies the default folder in which virtual machine (VM) + definitions are stored. Valid values are + <literal>default</literal>, which specifies the default + storage folder, or the name of the folder to use. See + <xref linkend="vboxconfigdata" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>proxymode</literal></term> + <listitem><para> + Configures the mode for an HTTP proxy server. Valid values + are as follows: + </para><variablelist> + <varlistentry> + <term><literal>manual</literal></term> + <listitem><para> + Configure the URL of a HTTP proxy server manually, + using the <literal>proxyurl</literal> property value. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>noproxy</literal></term> + <listitem><para> + Do not use an HTTP proxy server. A direct connection + to the Internet is used. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>system</literal></term> + <listitem><para> + Detect the proxy settings automatically for the host + network. This is the default value. + </para></listitem> + </varlistentry> + </variablelist></listitem> + </varlistentry> + <varlistentry> + <term><literal>proxyurl</literal></term> + <listitem><para> + Specifies the URL for an HTTP proxy server when you specify + a manual proxy by setting the <literal>proxymode</literal> + property to <literal>manual</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>vrdeauthlibrary</literal></term> + <listitem><para> + Specifies which library to use when external authentication + has been configured for a particular VM. Valid values are + <literal>default</literal>, which specifies the default + library, or the name of the library to use. See + <xref linkend="vbox-auth" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>vrdeextpack</literal></term> + <listitem><para> + Specifies the library that implements the VirtualBox Remote + Desktop Extension (RDE). Valid values are + <literal>null</literal>, which disables the RDE, or the name + of the library to use. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>websrvauthlibrary</literal></term> + <listitem><para> + Specifies which library the web service uses to authenticate + users. Valid values are <literal>default</literal>, which + specifies the default library, <literal>null</literal>, + which disables authentication, or the name of the library to + use. For information about the &product-name; web service, + see <xref linkend="VirtualBoxAPI" />. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command configures &product-name; to use the + specified HTTP proxy server. + </para> +<screen>$ VBoxManage setproperty proxymode manual +$ VBoxManage setproperty proxyurl "http://myproxy.com:8080"</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-startvm" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-sharedfolder.xml b/doc/manual/en_US/man_VBoxManage-sharedfolder.xml new file mode 100644 index 00000000..04b7d593 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-sharedfolder.xml @@ -0,0 +1,212 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage sharedfolder +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-sharedfolder" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage sharedfolder</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-sharedfolder</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-sharedfolder</refname> + <refpurpose>add and remove shared folders</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-sharedfolder-add"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage sharedfolder add</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="req">--name=<replaceable>name</replaceable></arg> + <arg choice="req">--hostpath=<replaceable>hostpath</replaceable></arg> + <arg>--readonly</arg> + <arg>--transient</arg> + <arg>--automount</arg> + <arg>--auto-mount-point=<replaceable>path</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-sharedfolder-remove"> + <command>VBoxManage sharedfolder remove</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="req">--name=<replaceable>name</replaceable></arg> + <arg>--transient</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + Shared folders enable you to share data between the host system + and guests. To use shared folders, you must first install the + &product-name; Guest Additions software on the guest OS. + </para> + <para> + The shared folder is associated with a share name and the full + path name of the folder or directory on the host system. The share + name is a unique name within the namespace of the host OS. + </para> + <refsect2 id="vboxmanage-sharedfolder-add"> + <title>Add a Shared Folder</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage sharedfolder add</command> command + creates a shared folder. The folder you specify is on the host + computer. When configured, the contents of the folder on the + host system can be shared with the guest OS. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the name or UUID of the guest VM that shares a + folder with the host system. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--name=<replaceable>name</replaceable></term> + <listitem><para> + Specifies the name of the share, which is a unique name + within the namespace of the host OS. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--hostpath=<replaceable>hostpath</replaceable></term> + <listitem><para> + Specifies the absolute path of the folder or directory on + the host OS to share with the guest OS. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--readonly</term> + <listitem><para> + Specifies that the share has only read-only access to + files at the host path. + </para><para> + By default, shared folders have read-write access to the + files at the host path. However on Linux distributions, + shared folders are mounted with 770 file permissions with + the <literal>root</literal> user and the + <literal>vboxsf</literal> group. By using this option, the + file permissions become 700. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--transient</term> + <listitem><para> + Specifies that the share is transient, which means that it + can be added and removed at runtime and does not persist + after the VM stops. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--automount</term> + <listitem><para> + Specifies that the share is automatically mounted. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--auto-mount-point=<replaceable>path</replaceable></term> + <listitem><para> + Specifies the mount point of the share. This guest OS specific. + </para><para> + For Windows and OS/2 guest this must be an unused drive letter. + If left blank (or if the drive letter is already in use), the + last unused drive letter is used instead (i.e. searching from + <literal>Z:</literal> thru <literal>A:</literal>). + </para><para> + For Linux, Solaris and other unix guest, it must be an absolute + path like <filename>/mnt/mysharedfolder</filename>. If left + empty the default location is + <filename>/media/sf_<replaceable>sharename</replaceable></filename>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-sharedfolder-remove"> + <title>Remove a Shared Folder</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage sharedfolder remove</command> command + removes a shared folder. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the name or UUID of the guest VM that shares a + folder with the host system. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--name=<replaceable>name</replaceable></term> + <listitem><para> + Specifies the name of the share to remove. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--transient</term> + <listitem><para> + Specifies that the share is transient, which means that it + can be added and removed at runtime and does not persist + after the VM stops. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command creates a shared folder called + <filename>o7share</filename> for the <filename>ol7</filename> VM. + The share is mounted automatically when the VM is started. + </para> +<screen>$ VBoxManage sharedfolder add ol7 --name ol7share --hostpath "/home/user/ol7share" --automount</screen> + <para> + The following command removes the shared folder called + <filename>o7share</filename> for the <filename>ol7</filename> VM. + </para> +<screen>$ VBoxManage sharedfolder remove ol7 --name ol7share</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-showmediuminfo.xml b/doc/manual/en_US/man_VBoxManage-showmediuminfo.xml new file mode 100644 index 00000000..55d06f33 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-showmediuminfo.xml @@ -0,0 +1,142 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage showmediuminfo +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-showmediuminfo" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage showmediuminfo</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-showmediuminfo</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-showmediuminfo</refname> + <refpurpose>show information about a medium</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-showmediuminfo"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage showmediuminfo</command> + <group> + <arg choice="plain">disk</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">floppy</arg> + </group> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>filename</replaceable></arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage showmediuminfo</command> command shows the + following information about a medium: + </para> + <itemizedlist> + <listitem><para> + Size + </para></listitem> + <listitem><para> + Size on disk + </para></listitem> + <listitem><para> + Type + </para></listitem> + <listitem><para> + In use by virtual machines (VMs) + </para></listitem> + </itemizedlist> + <para> + The medium must be specified either by its UUID, if the medium is + registered, or by its filename. Registered images can be listed + using <command>VBoxManage list hdds</command>, <command>VBoxManage + list dvds</command>, or <command>VBoxManage list + floppies</command>, as appropriate. + </para> + <para> + For backward compatibility, you can also use the + <command>showvdiinfo</command> command to obtain information about + the medium. + </para> + <variablelist> + <varlistentry> + <term><literal>disk</literal> | <literal>dvd</literal> | <literal>floppy</literal></term> + <listitem><para> + Specifies the type of medium. Valid values are + <literal>disk</literal> (hard drive), + <literal>dvd</literal>, or <literal>floppy</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>filename</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or + absolute path name of the medium or image. + </para><para> + If the medium is registered, you can specify the UUID. You + can also list registered images by using the + <command>VBoxManage list hdds</command>, <command>VBoxManage + list dvds</command>, or <command>VBoxManage list + floppies</command> command. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command shows information about the + <filename>disk01.vdi</filename> disk image: + </para> +<screen>$ VBoxManage showmediuminfo disk01.vdi</screen> + <para> + The following command shows information about the + <filename>floppy01.img</filename> floppy disk image. + </para> +<screen>$ VBoxManage showmediuminfo floppy floppy01.img</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-list" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-showvminfo.xml b/doc/manual/en_US/man_VBoxManage-showvminfo.xml new file mode 100644 index 00000000..09967b58 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-showvminfo.xml @@ -0,0 +1,221 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage showvminfo +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-showvminfo" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-18 00:40:56 +0100 (Wed, 18 Jan 2023) $</pubdate> + <title>VBoxManage showvminfo</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-showvminfo</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-showvminfo</refname> + <refpurpose>show configuration information or log file contents for a virtual + machine</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-showvminfo-default"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage showvminfo</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--details</arg> + <arg>--machinereadable</arg> + <arg>--password-id</arg> + <arg>--password</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-showvminfo-log"> + <command>VBoxManage showvminfo</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="req">--log=<replaceable>index</replaceable></arg> + <arg>--password-id <replaceable>id</replaceable></arg> + <arg>--password <replaceable>file</replaceable>|-</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage showvminfo</command> command outputs + configuration information or log file contents for a specified + virtual machine (VM). + </para> + <refsect2 id="vboxmanage-showvminfo-default"> + <title>Viewing Virtual Machine Information</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage showvminfo</command> command outputs + information about the specified VM in a detailed format or in a + machine-readable format. + </para> + <para> + The <command>VBoxManage showvminfo</command> command shows the + same information for the specified VM in the same format as the + <command>VBoxManage list vms --long</command> command. + </para> + <variablelist> + <varlistentry> + <term><option>--details</option></term> + <listitem><para> + Includes detailed information about the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--machinereadable</option></term> + <listitem><para> + Specifies that the VM information be in a machine-readable + format. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password-id <replaceable>id</replaceable></option></term> + <listitem><para> + Specifies password id of the VM if it is encrypted. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password <replaceable>file</replaceable>|-</option></term> + <listitem><para> + Specifies password of the VM if it is encrypted. Either + specify the absolute pathname of a password file on the + host operating system, or <literal>-</literal> to prompt + you for the password. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-showvminfo-log"> + <title>Viewing Virtual Machine Log Contents</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage showvminfo --log</command> command + outputs the contents of one of the specified VM's log files. + </para> + <variablelist> + <varlistentry> + <term><option>--log=<replaceable>index</replaceable></option></term> + <listitem><para> + Specifies a numerical index that identifies the log file. + </para><para> + The index value starts at <literal>0</literal>, which + indicates the <filename>VBox.log</filename> file. An index + value of <literal>1</literal> indicates the + <filename>VBoxHardening.log</filename> file. Index values + starting at <literal>2</literal> indicate other log files, + such as the <filename>VBox.log.1</filename> file. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password-id <replaceable>id</replaceable></option></term> + <listitem><para> + Specifies password id of the VM if it is encrypted. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password <replaceable>file</replaceable>|-</option></term> + <listitem><para> + Specifies password of the VM if it is encrypted. Either + specify the absolute pathname of a password file on the + host operating system, or <literal>-</literal> to prompt + you for the password. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following example shows typical output for this command: + </para> +<screen>$ VBoxManage showvminfo "Windows 10" +VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable> +Copyright (C) 2005-2023 Oracle and/or its affiliates + +Name: Windows 10 +Groups: / +Guest OS: Windows 10 (64-bit) +UUID: 1bf3464d-57c6-4d49-92a9-a5cc3816b7e7 +Config file: /home/username/VirtualBox VMs/Windows 10/Windows 10.vbox +Snapshot folder: /home/username/VirtualBox VMs/Windows 10/Snapshots +Log folder: /home/username/VirtualBox VMs/Windows 10/Logs +Hardware UUID: 1bf3464d-57c6-4d49-92a9-a5cc3816b7e7 +Memory size: 2048MB +Page Fusion: off +VRAM size: 12MB +CPU exec cap: 100% +...</screen> + <para> + The following example shows the information output in a + machine-readable format, which shows the entries as a + <replaceable>property</replaceable>=<replaceable>value</replaceable> + string: + </para> +<screen>$ VBoxManage showvminfo "Windows 10" --machinereadable +... +groups="/" +ostype="Windows 10 (64-bit)" +UUID="1bf3464d-57c6-4d49-92a9-a5cc3816b7e7" +...</screen> + <para> + The following example shows the contents of the + <filename>VBox.log</filename> log file: + </para> +<screen>$ VBoxManage showvminfo "Windows 10" --log 0 +00:00:02.895106 VirtualBox VM 6.0.0_RC1 r127378 linux.amd64 (Dec 10 2018 17:16:06) release log +00:00:02.895109 Log opened 2018-12-14T14:31:44.088259000Z +00:00:02.895111 Build Type: release +00:00:02.895115 OS Product: Linux +00:00:02.895117 OS Release: 4.1.12-61.1.22.el7uek.x86_64 +00:00:02.895119 OS Version: #2 SMP Fri Dec 2 09:28:44 PST 2016 +...</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-list" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-signova.xml b/doc/manual/en_US/man_VBoxManage-signova.xml new file mode 100644 index 00000000..58e50f47 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-signova.xml @@ -0,0 +1,144 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage signova +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-signova" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage signova</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-signova</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-signova</refname> + <refpurpose>Digitally sign an OVA</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-signova"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage signova</command> + <arg choice="req"><replaceable>ova</replaceable></arg> + <arg choice="req">--certificate=<replaceable>file</replaceable></arg> + <arg choice="req">--private-key=<replaceable>file</replaceable></arg> + <group> + <arg choice="plain">--private-key-password-file=<replaceable>password-file</replaceable></arg> + <arg choice="plain">--private-key-password=<replaceable>password</replaceable></arg> + </group> + <arg>--digest-type=<replaceable>type</replaceable></arg> + <group> + <arg choice="plain">--pkcs7</arg> + <arg choice="plain">--no-pkcs7</arg> + </group> + <arg>--intermediate-cert=<replaceable>file</replaceable></arg> + <arg>--force</arg> + <arg>--verbose</arg> + <arg>--quiet</arg> + <arg>--dry-run</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage signova</command> command adds a digital + signature to an OVA file. + </para> + <!-- Add more description here --> + <variablelist> + <varlistentry> + <term><replaceable>ova</replaceable></term> + <listitem><para>The OVA file to sign.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--certificate=<replaceable>file</replaceable></option></term> + <listitem><para>File containing the certificate that the OVA should be + signed with. This can either be in PEM format (base64) or DER (binary), + the command will detect which.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--private-key=<replaceable>file</replaceable></option></term> + <listitem><para>The file containing the private key. This can either be + in PEM (base64) or DER (binary) format, the command will detect + which.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--private-key-password-file=<replaceable>password-file</replaceable></option></term> + <listitem><para>File containing the private key password.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--private-key-password=<replaceable>password</replaceable></option></term> + <listitem><para>The private key password. <!-- add warning about visibility --> </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--digest-type=<replaceable>type</replaceable></option></term> + <listitem> + <para>Select the cryptographic digest algorithm to use in the + signing. Possible values: SHA-256 (default), SHA-512 and SHA-1.</para> + <para>Some older versions of OVFTool and other VMware produces may + require <option>--digest-type=sha-1</option> to accept the OVA.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--pkcs7</option>, <option>--no-pkcs7</option></term> + <listitem><para>Enables or disables the creation of an additional + PKCS#7/CMS signature. This is enabled by default.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--intermediate-cert=<replaceable>file</replaceable></option></term> + <listitem><para>File containing an intermediary certificate that should be + included in the optional PKCS#7/CMS signature. Like the others, the file can + either be in PEM or DER format. This option can be repeated to add + multiple intermediate certificates. This option implies the + <option>--pkcs7</option> option.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--force</option></term> + <listitem><para>Overwrite existing signature if present. The default + behaviour is to fail if the OVA is already signed.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dry-run</option></term> + <listitem><para>Do not actually modify the OVA, just test-run the signing operation.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>-v</option>, <option>--verbose</option>, <option>-q</option>, <option>--quiet</option></term> + <listitem><para>Controls the verbositity of the command execution. The + <option>--verbose</option> option can be used multiple times to get more output. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> + diff --git a/doc/manual/en_US/man_VBoxManage-snapshot.xml b/doc/manual/en_US/man_VBoxManage-snapshot.xml new file mode 100644 index 00000000..a49875d8 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-snapshot.xml @@ -0,0 +1,403 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage snapshot +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-snapshot" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage snapshot</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-snapshot</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-snapshot</refname> + <refpurpose>manage virtual machine snapshots</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-snapshot"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-snapshot-take"> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + + <arg choice="plain">take</arg> + + <arg choice="req"><replaceable>snapshot-name</replaceable></arg> + + <arg>--description=<replaceable>description</replaceable></arg> + + <arg>--live</arg> + + <arg>--uniquename Number,Timestamp,Space,Force</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-snapshot-delete"> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + + <arg choice="plain">delete</arg> + + <arg choice="req"><replaceable>snapshot-name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-snapshot-restore"> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + + <arg choice="plain">restore</arg> + + <arg choice="req"><replaceable>snapshot-name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-snapshot-restorecurrent"> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + + <arg choice="plain">restorecurrent</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-snapshot-edit"> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + + <arg choice="plain">edit</arg> + + <group choice="req"> + <arg choice="plain"><replaceable>snapshot-name</replaceable></arg> + <arg choice="plain">--current</arg> + </group> + + <arg>--description=<replaceable>description</replaceable></arg> + + <arg>--name=<replaceable>new-name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-snapshot-list"> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + + <arg choice="plain">list</arg> + + <group><arg>--details</arg><arg>--machinereadable</arg></group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-snapshot-showvminfo"> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + + <arg choice="plain">showvminfo</arg> + + <arg choice="req"><replaceable>snapshot-name</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage snapshot</command> command manages + snapshots. + </para> + <para> + &product-name; uses the snapshot to capture the state of a virtual + machine (VM). You can later use the snapshot to revert to the + state described by the snapshot. + </para> + <para> + A snapshot is a complete copy of a VM's settings. If you take the + snapshot while the VM is running, the snapshot also includes the + VM's state file. + </para> + <para> + After you take a snapshot, &product-name; creates a + <emphasis>differencing hard disk</emphasis> for each normal hard + disk that is associated with the host machine. When you restore a + snapshot, &product-name; uses these differencing files to quickly + reset the contents of the VM's virtual hard disks. + </para> + <para> + For each <command>VBoxManage snapshot</command> command, you must + specify the name or the universal unique identifier (UUID) of the + VM for which you want to take a snapshot. + </para> + <refsect2> + <title>General Command Operand</title> + <variablelist> + <varlistentry> + <term><replaceable>uuid|vmname</replaceable></term> + <listitem><para> + Specifies the UUID or name of the VM. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-snapshot-take"> + <title>Take a Snapshot of a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage snapshot take</command> command takes a + snapshot of the current state of the VM. You must supply a name + for the snapshot and can optionally supply a description. The + new snapshot is inserted into the snapshots tree as a child of + the current snapshot and then becomes the new current snapshot. + </para> + <variablelist> + <varlistentry> + <term><option>--description=<replaceable>description</replaceable></option></term> + <listitem><para> + Specifies a description of the snapshot. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--live</option></term> + <listitem><para> + Specifies that the VM is not stopped while you create the + snapshot. This operation is know as live snapshotting. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uniquename Number,Timestamp,Space,Force</option></term> + <listitem><para> + TBD. + </para><remark> + What does this option do and how is it used? + </remark></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>snapshot-name</replaceable></term> + <listitem><para> + Specifies the name of the snapshot to create. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-snapshot-delete"> + <title>Delete a Snapshot</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage snapshot delete</command> command + removes the specified snapshot. + </para> + <para> + The delete operation may take some time to finish. This is + because the differencing images that are associated with the + snapshot may need to be merged with their child differencing + images. + </para> + <variablelist> + <varlistentry> + <term><replaceable>snapshot-name</replaceable></term> + <listitem><para> + Specifies the UUID or name of the snapshot. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-snapshot-restore"> + <title>Restore a Snapshot</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage snapshot restore</command> command + restores the specified snapshot. This operation resets the VM's + settings and current state to that of the snapshot. The state of + the VM on which you restore a snapshot is lost. When restored, + the specified snapshot becomes the new current snapshot and + subsequent snapshots are children of that snapshot. + </para> + <variablelist> + <varlistentry> + <term><replaceable>snapshot-name</replaceable></term> + <listitem><para> + Specifies the UUID or name of the snapshot. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-snapshot-restorecurrent"> + <title>Restore the Current Snapshot</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage snapshot restorecurrent</command> + command restores the current snapshot. The current snapshot is + the one from which the current state is derived. This command is + equivalent to using the <command>VBoxManage snapshot + restore</command> command and specifying the name or UUID of the + current snapshot. + </para> + </refsect2> + <refsect2 id="vboxmanage-snapshot-edit"> + <title>Change the Name or Description of an Existing Snapshot</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage snapshot edit</command> command enables + you to change the name or the description of a specified + snapshot. + </para> + <variablelist> + <varlistentry> + <term><replaceable>snapshot-name</replaceable></term> + <listitem><para> + Specifies the UUID or name of the snapshot to edit. + </para><para> + This option is mutually exclusive with the + <option>--current</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--current</option></term> + <listitem><para> + Specifies that you update the current version of the + snapshot. + </para><para> + This option is mutually exclusive with a specific snapshot + name or its UUID. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--description=<replaceable>description</replaceable></option></term> + <listitem><para> + Specifies a new description for the snapshot. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--name=<replaceable>new-name</replaceable></option></term> + <listitem><para> + Specifies a new name for the snapshot. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-snapshot-list"> + <title>List the Snapshots</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage snapshot list</command> command lists + all the snapshots for a VM. + </para> + <variablelist> + <varlistentry> + <term><option>--details</option></term> + <listitem><para> + Specifies that the output shows detailed information about + the snapshot. + </para><para> + This option is mutually exclusive with the + <option>--machinereadable</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--machinereadable</option></term> + <listitem><para> + Specifies that the output is shown in a machine-readable + format. + </para><para> + This option is mutually exclusive with the + <option>--details</option> option. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-snapshot-showvminfo"> + <title>Show Information About a Snapshot's Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage snapshot showvminfo</command> command + enables you to view the VM settings that are part of an existing + snapshot. + </para> + <variablelist> + <varlistentry> + <term><replaceable>snapshot-name</replaceable></term> + <listitem><para> + Specifies the UUID or name of the snapshot. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following command creates a snapshot of the + <computeroutput>ol7u4</computeroutput> VM. The snapshot is called + <computeroutput>ol7u4-snap-001</computeroutput>. The command uses + the <option>--description</option> option to provide a description + of the snapshot contents. + </para> +<screen> +$ VBoxManage snapshot ol7u4 take ol7u4-snap-001 \ +--description="Oracle Linux 7.4" +</screen> + <para> + The following command lists the snapshots for the + <computeroutput>ol7u4</computeroutput> VM. + </para> +<screen> +$ VBoxManage snapshot ol7u4 list +</screen> + <para> + The following command changes the description for the + <computeroutput>ol7u4-snap-001</computeroutput> snapshot of the + <computeroutput>ol7u4</computeroutput> VM. + </para> +<screen> +$ VBoxManage snapshot ol7u4 edit ol7u4-snap-001 \ +--description="Oracle Linux 7.4 with UEK4 kernel" +</screen> + <para> + The following command shows VM settings for the + <computeroutput>ol7u1-snap-001</computeroutput> snapshot of the + <computeroutput>ol7u4</computeroutput> VM. + </para> +<screen> +$ VBoxManage snapshot ol7u4 showvminfo ol7u4-snap-001 +Name: ol7u4 +Groups: / +Guest OS: Oracle (64-bit) +UUID: 43349d78-2ab3-4cb8-978f-0e755cd98090 +Config file: C:\Users\user1\VirtualBox VMs\ol7u4\ol7u4.vbox +... +Snapshots: + + Name: ol7u4-snap-001 (UUID: 1cffc37d-5c37-4b86-b9c5-a0f157a55f43) + Description: Oracle Linux 7.4 with UEK4 kernel +</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-startvm.xml b/doc/manual/en_US/man_VBoxManage-startvm.xml new file mode 100644 index 00000000..f7d104fb --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-startvm.xml @@ -0,0 +1,195 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage startvm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-startvm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage startvm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-startvm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-startvm</refname> + <refpurpose>start a virtual machine</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-startvm"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage startvm</command> + <group choice="req" rep="repeat"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--putenv=<replaceable>name</replaceable>[=<replaceable>value</replaceable>]</arg> + <arg>--type=<group> + <arg choice="plain">gui</arg> + <arg choice="plain">headless</arg> + <arg choice="plain">sdl</arg> + <arg choice="plain">separate</arg> + </group></arg> + <arg choice="plain">--password <replaceable>file</replaceable></arg> + <arg choice="plain">--password-id <replaceable>password identifier</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage startvm</command> command starts an + &product-name; virtual machine (VM) that is in the Powered Off or + Saved state. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the name or Universally Unique Identifier (UUID) + of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--putenv=<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term> + <listitem><para> + Assigns a value to an environment variable as a name-value + pair. For example, VBOX_DISABLE_HOST_DISK_CACHE=1. + </para><para> + The short form of this option is <option>-E</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--type=gui | headless | sdl | separate</option></term> + <listitem><para> + Specifies the frontend used to start the VM. + </para><para> + You can use the <command>VBoxManage setproperty</command> + command to set a global default value for the frontend. + Alternatively, you can use the <command>VBoxManage + modifyvm</command> command to specify a default frontend + value for a specific VM. If neither a global or per-VM + default value is set and you do not specify the + <option>--type</option> option, then the VM opens in a + window on the host desktop. + </para><para> + The <option>--type</option> option accepts the following + values: + </para><variablelist> + <varlistentry> + <term><literal>gui</literal></term> + <listitem><para> + Starts a VM in a graphical user interface (GUI) + window. This is the default. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>headless</literal></term> + <listitem><para> + Starts a VM for remote display only. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>sdl</literal></term> + <listitem><para> + Starts a VM using the VBoxSDL frontend. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>separate</literal></term> + <listitem><para> + Starts a VM with a detachable user interface (UI), + which means that the VM runs headless with the UI in a + separate process. + </para><para> + This is an experimental feature that lacks certain + functionality, such as 3D acceleration. + </para></listitem> + </varlistentry> + </variablelist></listitem> + </varlistentry> + <varlistentry> + <term><option>--password</option></term> + <listitem> + <para> + Use the <option>--password</option> to supply the encryption + password. Either specify the absolute pathname of a password file + on the host operating system, or <literal>-</literal> to prompt + you for the password on the command line. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--password-id</option></term> + <listitem> + <para> + Use the <option>--password-id</option> option to specify the + id the password is supplied for. + </para> + </listitem> + </varlistentry> + </variablelist> + <note> + <para> + If a VM fails to start with a particular frontend and the error + information is inconclusive, consider starting the VM directly + by running the frontend. This workaround might provide + additional error information. + </para> + </note> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command starts the <literal>ol7u6</literal> VM: + </para> +<screen>$ VBoxManage startvm ol7u6</screen> + <para> + The following command starts the + <literal>ol7u6-mininstall</literal> VM in headless mode. + </para> +<screen>$ VBoxManage startvm ol7u6-mininstall --type headless</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> +<!--<xref linkend="vboxmanage-vboxheadless" />--> + <xref linkend="vboxheadless" />, + <xref linkend="vboxmanage-setproperty" />, + <xref linkend="vboxmanage-modifyvm" />. + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-storageattach.xml b/doc/manual/en_US/man_VBoxManage-storageattach.xml new file mode 100644 index 00000000..4d8608d4 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-storageattach.xml @@ -0,0 +1,549 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage storageattach +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-storageattach" lang="en"> + <refentryinfo> + <pubdate>August 2019</pubdate> + <title>VBoxManage storageattach</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-storageattach</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-storageattach</refname> + <refpurpose>attach, remove, and modify storage media used by a virtual machine</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-storageattach"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage storageattach</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="req">--storagectl=<replaceable>name</replaceable></arg> + <arg>--bandwidthgroup=<group choice="plain"> + <arg choice="plain">name</arg> + <arg choice="plain">none</arg> + </group></arg> + <arg>--comment=<replaceable>text</replaceable></arg> + <arg>--device=<replaceable>number</replaceable></arg> + <arg>--discard=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--encodedlun=<replaceable>lun</replaceable></arg> + <arg>--forceunmount</arg> + <arg>--hotpluggable=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--initiator=<replaceable>initiator</replaceable></arg> + <arg>--intnet</arg> + <arg>--lun=<replaceable>lun</replaceable></arg> + <arg>--medium=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">emptydrive</arg> + <arg choice="plain">additions</arg> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>filename</replaceable></arg> + <arg choice="plain">host:<replaceable>drive</replaceable></arg> + <arg choice="plain">iscsi</arg> + </group></arg> + <arg>--mtype=<group choice="plain"> + <arg choice="plain">normal</arg> + <arg choice="plain">writethrough</arg> + <arg choice="plain">immutable</arg> + <arg choice="plain">shareable</arg> + <arg choice="plain">readonly</arg> + <arg choice="plain">multiattach</arg> + </group></arg> + <arg>--nonrotational=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--passthrough=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--passwordfile=<replaceable>file</replaceable></arg> + <arg>--password=<replaceable>password</replaceable></arg> + <arg>--port=<replaceable>number</replaceable></arg> + <arg>--server=<group choice="plain"> + <arg choice="plain"><replaceable>name</replaceable></arg> + <arg choice="plain"><replaceable>ip</replaceable></arg> + </group></arg> + <arg>--setparentuuid=<replaceable>uuid</replaceable></arg> + <arg>--setuuid=<replaceable>uuid</replaceable></arg> + <arg>--target=<replaceable>target</replaceable></arg> + <arg>--tempeject=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--tport=<replaceable>port</replaceable></arg> + <arg>--type=<group choice="plain"> + <arg choice="plain">dvddrive</arg> + <arg choice="plain">fdd</arg> + <arg choice="plain">hdd</arg> + </group></arg> + <arg>--username=<replaceable>username</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage storageattach</command> command enables + you to manage a storage medium that you connected to a storage + controller by using the <command>VBoxManage storagectl</command> + command. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or the + name of the virtual machine (VM). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--storagectl=<replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the name of the storage controller. Use the + <command>VBoxManage showvminfo</command> command to list the + storage controllers that are attached to the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--port=<replaceable>number</replaceable></option></term> + <listitem><para> + Specifies the port number of the storage controller to + modify. You must specify this option unless the storage + controller has only a single port. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--device=<replaceable>number</replaceable></option></term> + <listitem><para> + Specifies the port's device number to modify. You must + specify this option unless the storage controller has only + one device per port. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--type=dvddrive | fdd | hdd</option></term> + <listitem><para> + Specifies the drive type to which the medium is associated. + Only omit this option if the medium type can be determined + by using the <option>--medium</option> option or by + information provided by an earlier medium attachment + command. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--medium=none | emptydrive | additions | <replaceable>uuid</replaceable> | <replaceable>filename</replaceable> | host:<replaceable>drive</replaceable> | iscsi</option></term> + <listitem><para> + Specifies one of the following values: + </para><variablelist> + <varlistentry> + <term><literal>none</literal></term> + <listitem><para> + Removes any existing device from the specified slot. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>emptydrive</literal></term> + <listitem><para> + For a virtual DVD or floppy drive only. + </para><para> + Makes the device slot behave like a removeable drive + into which no media has been inserted. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>additions</literal></term> + <listitem><para> + For a virtual DVD drive only. + </para><para> + Attaches the VirtualBox Guest Additions image to the + specified device slot. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable></term> + <listitem><para> + Specifies the UUID of a storage medium to attach to + the specified device slot. The storage medium must + already be known to &product-name;, such as a storage + medium that is attached to another VM. Use the + <command>VBoxManage list</command> command to list + media. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>filename</replaceable></term> + <listitem><para> + Specifies the full path of an existing disk image to + attach to the specified device slot. The disk image + can be in ISO, RAW, VDI, VMDK, or other format. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>host:<replaceable>drive</replaceable></literal></term> + <listitem><para> + For a virtual DVD or floppy drive only. + </para><para> + Connects the specified device slot to the specified + DVD or floppy drive on the host computer. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>iscsi</literal></term> + <listitem><para> + For virtual hard disks only. + </para><para> + Specifies an iSCSI target for which you must specify + additional information. See + <xref linkend="storage-iscsi" />. + </para></listitem> + </varlistentry> + </variablelist><para> + For removeable media such as floppies and DVDs, you can make + configuration changes while a VM is running. Changes to + devices or hard disk device slots require that the VM be + powered off. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mtype=normal | writethrough | immutable | shareable | readonly | multiattach</option></term> + <listitem><para> + Specifies how this medium behaves with respect to snapshots + and write operations. See <xref linkend="hdimagewrites" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--comment=<replaceable>text</replaceable></option></term> + <listitem><para> + Specifies an optional description to store with the medium. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--setuuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Modifies the UUID of a medium before attaching it to a VM. + </para><para> + This is an expert option. Inappropriate values might make + the medium unusable or lead to broken VM configurations if + another VM already refers to the same medium. + </para><para> + Using the <option>--setuuid=""</option> option + assigns a new random UUID to an image, which can resolve + duplicate UUID errors if you used a file copy utility to + duplicate an image. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--setparentuuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Modifies the parent UUID of a medium before attaching it to + a VM. + </para><para> + This is an expert option. Inappropriate values might make + the medium unusable or lead to broken VM configurations if + another VM already refers to the same medium. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--passthrough=on | off</option></term> + <listitem><para> + For a virtual DVD drive only. + </para><para> + Enables writing to a DVD. This feature is experimental, see + <xref linkend="storage-cds" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tempeject=on | off</option></term> + <listitem><para> + For a virtual DVD drive only. + </para><para> + Specifies whether to permit a temporary guest-triggered + medium eject operation. When set to <literal>on</literal>, + you can eject a medium. The ability for a guest-triggered + eject operation does not persist if the VM is powered off + and restarted. So, when you set this option to + <literal>on</literal> and the VM is restarted, the + originally configured medium is still in the drive. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nonrotational=on | off</option></term> + <listitem><para> + Enables you to specify that the virtual hard disk is + non-rotational. Some guest OSes, such as Windows 7 or later, + treat such disks as solid state drives (SSDs) and do not + perform disk fragmentation on them. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--discard=on | off</option></term> + <listitem><para> + Specifies whether to enable the auto-discard feature for a + virtual hard disk. When set to <literal>on</literal>, a VDI + image is shrunk in response to a <command>trim</command> + command from the guest OS. + </para><para> + The virtual hard disk must meet the following requirements: + </para><itemizedlist> + <listitem><para> + The disk format must be VDI. + </para></listitem> + <listitem><para> + The size of the cleared area of the disk must be at + least 1 MB. + </para></listitem> + <listitem><para> + Ensure that the space being trimmed is at least a 1 MB + contiguous block at a 1 MB boundary. + </para></listitem> + </itemizedlist><para> + Consider running defragmentation commands as background cron + jobs to save space. On Windows, run the <command>defrag.exe + /D</command> command. On Linux, run the <command>btrfs + filesystem defrag</command> command. + </para><note> + <para> + When you configure the guest OS to issue the + <command>trim</command> command, the guest OS typically + sees the disk as an SSD. + </para> + <para> + Ext4 supports the <option>-o discard</option> mount + option. Mac OS X might require additional settings. + Windows 7, 8, and 10 automatically detect and support + SSDs. The Linux <command>exFAT</command> driver from + Samsung supports the <command>trim</command> command. + </para> + </note><para> + The Microsoft implementation of exFAT might not support this + feature. + </para><para> + You can use other methods to issue trim commands. The Linux + <command>fstrim</command> command is part of the + <filename>util-linux</filename> package. Earlier solutions + required you to zero out unused areas by using the + <command>zerofree</command> or a similar command, and then + to compact the disk. You can only perform these steps when + the VM is offline. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bandwidthgroup=<replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the bandwidth group to use for the device. See + <xref linkend="storage-bandwidth-limit" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--forceunmount</option></term> + <listitem><para> + For a virtual DVD or floppy drive only. + </para><para> + Forcibly unmounts the DVD, CD, or floppy or mounts a new + DVD, CD, or floppy even if the previous removable storage is + locked by the guest for reading. See + <xref linkend="storage-cds" />. + </para></listitem> + </varlistentry> + </variablelist> + <para> + The following options are applicable when you specify the + <option>--medium=iscsi</option> option: + </para> + <variablelist> + <varlistentry> + <term><option>--server=<replaceable>hostname</replaceable> | <replaceable>IP-address</replaceable></option></term> + <listitem><para> + Specifies the host name or IP address of the iSCSI target. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--target=<replaceable>target</replaceable></option></term> + <listitem><para> + Specifies the target name string, which is determined by the + iSCSI target and is used to identify the storage resource. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tport=<replaceable>port</replaceable></option></term> + <listitem><para> + Specifies the TCP/IP port number of the iSCSI service on the + target. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--lun=<replaceable>LUN</replaceable></option></term> + <listitem><para> + Specifies the logical unit number (LUN) of the target + resource. For a single disk drive, the value is zero. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--encodedlun=<replaceable>LUN</replaceable></option></term> + <listitem><para> + Specifies the hexadecimal-encoded of the target resource. + For a single disk drive, the value is zero. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--username=<replaceable>username</replaceable></option></term> + <listitem><para> + Specifies the user name to use for target authentication. + </para><note> + <para> + Unless you provide a settings password, the user name is + stored as clear text in the XML machine configuration + file. + </para> + </note></listitem> + </varlistentry> + <varlistentry> + <term><option>--password=<replaceable>password</replaceable></option></term> + <listitem><para> + Specifies the password used for target authentication. + </para><note> + <para> + Unless you provide a settings password, this password is + stored as clear text in the XML machine configuration + file. When you specify a settings password for the first + time, the target authentication password is stored in + encrypted form. + </para> + </note><remark> + This design does not conform to Oracle's security + guidelines. You should not be able to specify a password on + the command line because the password can be seen in a + process listing. + </remark></listitem> + </varlistentry> + <varlistentry> + <term><option>--passwordfile=<replaceable>password-filename</replaceable></option></term> + <listitem><para> + Specifies a file that contains the target authentication + password as clear text. + </para><note> + <para> + Use permission and ownership settings to ensure that the + contents of this file cannot be read by unauthorized + users. + </para> + </note></listitem> + </varlistentry> + <varlistentry> + <term><option>--initiator=<replaceable>initiator</replaceable></option></term> + <listitem><para> + Specifies the iSCSI initiator. + </para><para> + The Microsoft iSCSI Initiator is a system, such as a server, + that attaches to an IP network and initiates requests and + receives responses from an iSCSI target. The SAN components + in the iSCSI initiator are largely analogous to Fibre + Channel SAN components, and they include the following: + </para><itemizedlist> + <listitem><para> + <emphasis role="bold">iSCSI driver.</emphasis> + Transports blocks of iSCSI commands over the IP network. + This iSCSI driver is installed on the iSCSI host and is + included with the Microsoft iSCSI Initiator. + </para></listitem> + <listitem><para> + <emphasis role="bold">Gigabit Ethernet + adapter.</emphasis> Connects to an iSCSI target. Use an + Ethernet adapter that can transmit 1000 megabits per + second (Mbps). Like standard 10/100 adapters, most + gigabit adapters use a preexisting Category 5 or + Category 6E cable. Each port on the adapter is + identified by a unique IP address. + </para></listitem> + <listitem><para> + <emphasis role="bold">iSCSI target.</emphasis> Is any + device that receives iSCSI commands. The device can be + an end node such as a storage device, or it can be an + intermediate device such as a network bridge between IP + and Fibre Channel devices. Each port on the storage + array controller or network bridge is identified by one + or more IP addresses. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--intnet</option></term> + <listitem><para> + Specifies whether to connect to the iSCSI target that uses + internal networking. This configuration requires further + configuration. See <xref linkend="iscsi-intnet" />. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command attaches the <filename>o7.vdi</filename> + disk image to the specified SATA storage controller on the + <filename>ol7</filename> VM. + </para> +<screen>$ storageattach ol7 --storagectl "SATA Controller" --port 0 --device 0 \ +--type hdd --medium /VirtualBox/ol7/ol7.vdi</screen> + <para> + The following command attaches the + <filename>o7-r6-dvd.iso</filename> DVD image to the specified IDE + storage controller on the <filename>ol7</filename> VM. + </para> +<screen>$ VBoxManage storageattach ol7 --storagectl "IDE Controller" --port 0 --device 0 \ +--type dvddrive --medium ol7-r6-dvd.iso</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-list" />, + <xref linkend="vboxmanage-showvminfo" />, + <xref linkend="vboxmanage-storagectl" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-storagectl.xml b/doc/manual/en_US/man_VBoxManage-storagectl.xml new file mode 100644 index 00000000..ff463c1b --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-storagectl.xml @@ -0,0 +1,205 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage storagectl +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-storagectl" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage storagectl</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-storagectl</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-storagectl</refname> + <refpurpose>manage a storage controller</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <cmdsynopsis id="synopsis-vboxmanage-storagectl"> + <command>VBoxManage storagectl</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="req">--name=<replaceable>controller-name</replaceable></arg> + <arg>--add=<group choice="plain"> + <arg choice="plain">floppy</arg> + <arg choice="plain">ide</arg> + <arg choice="plain">pcie</arg> + <arg choice="plain">sas</arg> + <arg choice="plain">sata</arg> + <arg choice="plain">scsi</arg> + <arg choice="plain">usb</arg> + </group></arg> + <arg>--controller=<group choice="plain"> + <arg choice="plain">BusLogic</arg> + <arg choice="plain">I82078</arg> + <arg choice="plain">ICH6</arg> + <arg choice="plain">IntelAhci</arg> + <arg choice="plain">LSILogic</arg> + <arg choice="plain">LSILogicSAS</arg> + <arg choice="plain">NVMe</arg> + <arg choice="plain">PIIX3</arg> + <arg choice="plain">PIIX4</arg> + <arg choice="plain">USB</arg> + <arg choice="plain">VirtIO</arg> + </group></arg> + <arg>--bootable=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--hostiocache=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--portcount=<replaceable>count</replaceable></arg> + <arg>--remove</arg> + <arg>--rename=<replaceable>new-controller-name</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage storagectl</command> command enables you + to attach, modify, and remove a storage controller. After you + configure the storage controller, you can use the + <command>VBoxManage storageattach</command> command to attach + virtual media to the controller. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or name + of the virtual machine (VM). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--name=<replaceable>controller-name</replaceable></option></term> + <listitem><para> + Specifies the name of the storage controller. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--add=<replaceable>system-bus-type</replaceable></option></term> + <listitem><para> + Specifies the type of the system bus to which to connect the + storage controller. Valid values are + <literal>floppy</literal>, <literal>ide</literal>, + <literal>pcie</literal>, <literal>sas</literal>, + <literal>sata</literal>, <literal>scsi</literal>, and + <literal>usb</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--controller=<replaceable>chipset-type</replaceable></option></term> + <listitem><para> + Specifies the chipset type to emulate for the specified + storage controller. Valid values are + <literal>BusLogic</literal>, <literal>I82078</literal>, + <literal>ICH6</literal>, <literal>IntelAHCI</literal>, + <literal>LSILogic</literal>, <literal>LSILogicSAS</literal>, + <literal>NVMe</literal>, <literal>PIIX3</literal>, + <literal>PIIX4</literal>, and <literal>USB</literal>. + </para><para> + The default value varies, according to the type of storage + controller. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--portcount=<replaceable>count</replaceable></option></term> + <listitem><para> + Specifies the number of ports that the storage controller + supports. Valid values depend on the type of storage + controller. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--hostiocache=on|off</option></term> + <listitem><para> + Specifies whether to use the host I/O cache for all disk + images attached to this storage controller. Valid values are + <literal>on</literal> and <literal>off</literal>. See + <xref linkend="iocaching" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bootable=on|off</option></term> + <listitem><para> + Specifies whether this controller is bootable. Valid values + are <literal>on</literal> and <literal>off</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--rename=<replaceable>new-controller-name</replaceable></option></term> + <listitem><para> + Specifies a new name for the storage controller. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--remove</option></term> + <listitem><para> + Removes a storage controller from the VM configuration. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command creates a SATA storage controller called + <literal>sata01</literal> and adds it to the + <literal>ol7</literal> VM. The storage controller emulates the + IntelAHCI chipset. + </para> +<screen>$ VBoxManage storagectl ol7 --name "sata01" --add sata --controller IntelAHCI</screen> + <para> + The following command creates an IDE storage controller called + <literal>ide01</literal> and adds it to the <literal>ol7</literal> + VM. + </para> +<screen>$ VBoxManage storagectl ol7 --name "ide01" --add ide</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-storageattach" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-unattended.xml b/doc/manual/en_US/man_VBoxManage-unattended.xml new file mode 100644 index 00000000..b7abf6b4 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-unattended.xml @@ -0,0 +1,256 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage unattended +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-unattended" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage unattended</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-unattended</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-unattended</refname> + <refpurpose>unattended guest OS installation</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-unattended-detect"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage unattended detect</command> + <arg choice="req">--iso=<replaceable>install-iso</replaceable></arg> + <arg>--machine-readable</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-unattended-install"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage unattended install</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="req">--iso=<replaceable>install-iso</replaceable></arg> + <arg>--user=<replaceable>login</replaceable></arg> + <arg>--password=<replaceable>password</replaceable></arg> + <arg>--password-file=<replaceable>file</replaceable></arg> + <arg>--full-user-name=<replaceable>name</replaceable></arg> + <arg>--key=<replaceable>product-key</replaceable></arg> + <arg>--install-additions</arg> + <arg>--no-install-additions</arg> + <arg>--additions-iso=<replaceable>add-iso</replaceable></arg> + <arg>--install-txs</arg> + <arg>--no-install-txs</arg> + <arg>--validation-kit-iso=<replaceable>testing-iso</replaceable></arg> + <arg>--locale=<replaceable>ll_CC</replaceable></arg> + <arg>--country=<replaceable>CC</replaceable></arg> + <arg>--time-zone=<replaceable>tz</replaceable></arg> + <arg>--hostname=<replaceable>fqdn</replaceable></arg> + <arg>--package-selection-adjustment=<replaceable>keyword</replaceable></arg> + <arg>--dry-run</arg> + <arg>--auxiliary-base-path=<replaceable>path</replaceable></arg> + <arg>--image-index=<replaceable>number</replaceable></arg> + <arg>--script-template=<replaceable>file</replaceable></arg> + <arg>--post-install-template=<replaceable>file</replaceable></arg> + <arg>--post-install-command=<replaceable>command</replaceable></arg> + <arg>--extra-install-kernel-parameters=<replaceable>params</replaceable></arg> + <arg>--language=<replaceable>lang</replaceable></arg> + <arg>--start-vm=<replaceable>session-type</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <refsect2 id="vboxmanage-unattended-detect"> + <title>unattended detect</title> + <remark role="help-copy-synopsis"/> + <para> + Detects the guest operating system (OS) on the specified installation ISO + and displays the result. This can be used as input when creating a VM for + the ISO to be installed in. + </para> + <variablelist> + <varlistentry> + <term><option>--iso=<replaceable>install-iso</replaceable></option></term> + <listitem><para>The installation ISO to run the detection on.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--machine-readable</option></term> + <listitem><para>Produce output that is simpler to parse from a script.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-unattended-install"> + <title>unattended install</title> + <remark role="help-copy-synopsis"/> + <para> + Reconfigures the specified VM for installation and optionally starts it up. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid|vmname</replaceable></term> + <listitem><para>Either the UUID or the name (case sensitive) of a VM.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--iso=<replaceable>install-iso</replaceable></option></term> + <listitem><para>The installation ISO to run the detection on.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--user=<replaceable>login</replaceable></option></term> + <listitem><para>The login name. (default: vboxuser)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password=<replaceable>password</replaceable></option></term> + <listitem> + <para>The login password. This is used for the user given by <option>--user</option> as well as the + root/administrator user. (default: changeme)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password-file=<replaceable>file</replaceable></option></term> + <listitem> + <para>Alternative to <option>--password</option> for providing the password. Special filename + <computeroutput>stdin</computeroutput> can be used to read the password from standard input.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--full-user-name=<replaceable>name</replaceable></option></term> + <listitem><para>The full user name. (default: --user)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--key=<replaceable>product-key</replaceable></option></term> + <listitem><para>The guest OS product key. Not all guest OSes requires this.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--install-additions</option>, <option>--no-install-additions</option></term> + <listitem><para>Whether to install the VirtualBox guest additions. (default: --no-install-addations)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--additions-iso=<replaceable>add-iso</replaceable></option></term> + <listitem> + <para>Path to the VirtualBox guest additions ISO. (default: installed/downloaded GAs)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--install-txs</option>, <option>--no-install-txs</option></term> + <listitem> + <para>Whether to install the test execution service (TXS) from the VirtualBox ValidationKit. + This is useful when preparing VMs for testing or similar. (default: --no-install-txs)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--validation-kit-iso=<replaceable>testing-iso</replaceable></option></term> + <listitem> + <para>Path to the VirtualBox ValidationKit ISO. This is required if <option>--install-txs</option> + is specified. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--locale=<replaceable>ll_CC</replaceable></option></term> + <listitem> + <para>The base locale specification for the guest, like en_US, de_CH, or nn_NO. (default: host or en_US)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--country=<replaceable>CC</replaceable></option></term> + <listitem><para>The two letter country code if it differs from the specified by <option>--location</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--time-zone=<replaceable>tz</replaceable></option></term> + <listitem><para>The time zone to set up the guest OS with. (default: host time zone or UTC)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--hostname=<replaceable>fqdn</replaceable></option></term> + <listitem> + <para>The fully qualified domain name of the guest machine. + (default: <replaceable>vmname</replaceable>.myguest.virtualbox.org)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--package-selection-adjustment=<replaceable>keyword</replaceable></option></term> + <listitem> + <para>Adjustments to the guest OS packages/components selection. This can be specfied more than once. Currently + the only recognized keyword is <computeroutput>minimal</computeroutput> which triggers a minimal installation for + some of the guest OSes.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dry-run</option></term> + <listitem><para>Do not create any files or make any changes to the VM configuration.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--start-vm=<replaceable>session-type</replaceable></option></term> + <listitem> + <para>Start the VM using the front end given by <replaceable>session-type</replaceable>. This is the same as + the <option>--type</option> option for the <computeroutput>startvm</computeroutput> command, but we have add + <computeroutput>none</computeroutput> for indicating that the VM should not be started. + (default: <computeroutput>none</computeroutput>)</para></listitem> + </varlistentry> + </variablelist> + + <para>Advanced options:</para> + <variablelist> + <varlistentry> + <term><option>--auxiliary-base-path=<replaceable>path</replaceable></option></term> + <listitem> + <para>The path prefix to the media related files generated for the installation. + (default: <replaceable>vm-config-dir</replaceable>/Unattended-<replaceable>vm-uuid</replaceable>-)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--image-index=<replaceable>number</replaceable></option></term> + <listitem><para>Windows installation image index. (default: 1)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--script-template=<replaceable>file</replaceable></option></term> + <listitem><para>The unattended installation script template. (default: IMachine::OSTypeId dependent)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--post-install-template=<replaceable>file</replaceable></option></term> + <listitem><para>The post installation script template. (default: IMachine::OSTypeId dependent)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--post-install-command=<replaceable>command</replaceable></option></term> + <listitem> + <para>A single command to run after the installation is completed. The exact format and exactly + when this is run is guest OS installer dependent.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--extra-install-kernel-parameters=<replaceable>params</replaceable></option></term> + <listitem> + <para> + List of extra linux kernel parameters to use during the installation. (default: IMachine::OSTypeId dependent) + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--language=<replaceable>lang</replaceable></option></term> + <listitem> + <para> + Specifies the UI language for a Windows installation. The <replaceable>lang</replaceable> is + generally on the form {ll}-{CC}. See detectedOSLanguages results from <command>VBoxManage unattended detect</command>. + (default: detectedOSLanguages[0])</para></listitem> + </varlistentry> + + </variablelist> + </refsect2> + + </refsect1> +</refentry> + diff --git a/doc/manual/en_US/man_VBoxManage-unregistervm.xml b/doc/manual/en_US/man_VBoxManage-unregistervm.xml new file mode 100644 index 00000000..81cc5a49 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-unregistervm.xml @@ -0,0 +1,132 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage unregistervm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-unregistervm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage unregistervm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-unregistervm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-unregistervm</refname> + <refpurpose>unregister a virtual machine</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-unregistervm"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage unregistervm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--delete</arg> + <arg>--delete-all</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage unregistervm</command> command unregisters + a virtual machine (VM). + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the name or Universally Unique Identifier (UUID) + of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--delete</option></term> + <listitem><para> + Deletes the following files related to the VM automatically: + </para><itemizedlist> + <listitem><para> + All hard disk image files, including differencing files. + </para></listitem> + <listitem><para> + All saved state files that the machine created, + including one for each snapshot. + </para></listitem> + <listitem><para> + XML VM machine definition file and its backups. + </para></listitem> + <listitem><para> + VM log files. + </para></listitem> + <listitem><para> + The empty directory associated with the unregistered VM. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--delete-all</option></term> + <listitem><para> + Deletes the files described in the <option>--delete</option> option, + as well as all DVDs and Floppy disks located in the VM folder and + attached only to this VM. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command unregisters a VM called + <literal>vm2</literal>. + </para> +<screen>$ VBoxManage unregistervm vm2</screen> + <para> + The following command unregisters a VM called + <literal>vm3</literal>. All files associated with the VM are + deleted. + </para> +<screen>$ VBoxManage unregistervm vm3 --delete +%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-registervm" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-updatecheck.xml b/doc/manual/en_US/man_VBoxManage-updatecheck.xml new file mode 100644 index 00000000..05acb108 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-updatecheck.xml @@ -0,0 +1,151 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage updatecheck +--> +<!-- + Copyright (C) 2020-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-updatecheck" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage updatecheck</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-updatecheck</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-updatecheck</refname> + <refpurpose>Checks for a newer version of VirtualBox</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-updatecheck-perform"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage updatecheck perform</command> + <arg>--machine-readable</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-updatecheck-list"> + <command>VBoxManage updatecheck list</command> + <arg>--machine-readable</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-updatecheck-modify"> + <command>VBoxManage updatecheck modify</command> + <group> + <arg choice="plain">--disable</arg> + <arg choice="plain">--enable</arg> + </group> + <arg>--channel=<replaceable>stable | withbetas | all</replaceable></arg> + <arg>--frequency=<replaceable>days</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <command>updatecheck</command> subcommand is used to check if a newer + version of VirtualBox is available. The two subcommand options of <command>updatecheck</command> + are used for modifying or viewing the settings associated with checking for a newer version + of VirtualBox.</para> + + <refsect2 id="vboxmanage-updatecheck-perform"> + <title>updatecheck perform</title> + <remark role="help-copy-synopsis"/> + <para> + Checks if a newer version of VirtualBox is available. + </para> + <variablelist> + <varlistentry> + <term><option>--machine-readable</option></term><listitem><para>Machine readable output.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-updatecheck-list"> + <title>updatecheck list</title> + <remark role="help-copy-synopsis"/> + <para> + Displays the current settings used for specifying when to check for a newer version of VirtualBox. + </para> + <variablelist> + <varlistentry> + <term><option>--machine-readable</option></term><listitem><para>Machine readable output.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-updatecheck-modify"> + <title>updatecheck modify</title> + <remark role="help-copy-synopsis"/> + <para> + Modifies the settings used for specifying when to check for a newer version of VirtualBox. + </para> + <variablelist> + <varlistentry> + <term><option>--enable</option></term><listitem><para>Enable the update check service.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--disable</option></term><listitem><para>Disable the update check service.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--channel=stable | withbetas | all</option></term> + <listitem><para>The preferred release type used for determining whether a newer version of VirtualBox is available. The default is 'stable'.</para> + <variablelist> + <varlistentry> + <term><option>stable</option></term> + <listitem><para>Checks for newer stable releases (maintenance and minor releases within the same major release) of VirtualBox.</para> </listitem> + </varlistentry> + <varlistentry> + <term><option>all</option></term> + <listitem><para>Checks for newer stable releases (maintenance and minor releases within the same major release) and major releases of VirtualBox.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>withbetas</option></term> + <listitem><para>Checks for newer stable releases (maintenance and minor releases within the same major release), major releases, and beta releases of VirtualBox.</para></listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--frequency=days</option></term> + <listitem><para>Specifies how often in days to check for a newer version of VirtualBox.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--proxy-mode=system | manual | none</option></term> + <listitem><para>Specifies the proxy mode to use.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--proxy-url=<address></option></term> + <listitem><para>Specifies the proxy address to use. Set to empty string to clear proxy address.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsect1> + +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-usbdevsource.xml b/doc/manual/en_US/man_VBoxManage-usbdevsource.xml new file mode 100644 index 00000000..7a5dd9d1 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-usbdevsource.xml @@ -0,0 +1,129 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage usbdevsource +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-usbdevsource" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage usbdevsource</title> + </refentryinfo> + + <refmeta> + <refentrytitle>vboxmanage-usbdevsource</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>vboxmanage-usbdevsource</refname> + <refpurpose>add and remove USB device sources</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-usbdevsource-add"> + <command>VBoxManage usbdevsource add</command> + <arg choice="req"><replaceable>source-name</replaceable></arg> + <arg choice="req">--backend=<replaceable>backend</replaceable></arg> + <arg choice="req">--address=<replaceable>address</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-usbdevsource-remove"> + <command>VBoxManage usbdevsource remove</command> + <arg choice="req"><replaceable>source-name</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage usbdevsource</command> command adds a USB + device source and makes it available to the guests on the host + system. You can also use this command to remove the USB device + source. + </para> + <refsect2 id="vboxmanage-usbdevsource-add"> + <title>Add a USB Device Source</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage usbdevsource add</command> command adds + a USB device source, which is available to all guests on the + host system. + </para> + <variablelist> + <varlistentry> + <term><replaceable>source-name</replaceable></term> + <listitem><para> + Specifies a unique name for the USB device source. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--address=<replaceable>address</replaceable></term> + <listitem><para> + Specifies the address of the USB backend. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--backend=<replaceable>backend</replaceable></term> + <listitem><para> + Specifies the USB proxy service backend to use. + </para><para> + For now only USBIP is supported to specify a remote + server using the USB/IP protocol. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-usbdevsource-remove"> + <title>Remove a USB Device</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage usbdevsource remove</command> command + removes a USB device. + </para> + <variablelist> + <varlistentry> + <term><replaceable>source-name</replaceable></term> + <listitem><para> + Specifies the name of the USB device source to remove. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command adds a USB device server called + <filename>hostusb01</filename>. + </para> +<screen>$ VBoxManage usbdevsource add hostusb01 --backend USBIP --address 10.0.1.16</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-usbfilter.xml b/doc/manual/en_US/man_VBoxManage-usbfilter.xml new file mode 100644 index 00000000..e8d88d62 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-usbfilter.xml @@ -0,0 +1,324 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage usbfilter +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-usbfilter" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage usbfilter</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-usbfilter</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-usbfilter</refname> + <refpurpose>manage USB filters</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <cmdsynopsis id="synopsis-vboxmanage-usbfilter-add"> + <command>VBoxManage usbfilter add</command> + <arg choice="req"><replaceable>index</replaceable>,0-<replaceable>N</replaceable></arg> + <arg choice="req">--target=<group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + <arg choice="plain">global</arg> + </group></arg> + <arg choice="req">--name=<replaceable>string</replaceable></arg> + <arg choice="req">--action=ignore | hold</arg> + <arg>--active=yes | no</arg> + <arg>--vendorid=<replaceable>XXXX</replaceable></arg> + <arg>--productid=<replaceable>XXXX</replaceable></arg> + <arg>--revision=<replaceable>IIFF</replaceable></arg> + <arg>--manufacturer=<replaceable>string</replaceable></arg> + <arg>--product=<replaceable>string</replaceable></arg> + <arg>--port=<replaceable>hex</replaceable></arg> + <arg>--remote=yes | no</arg> + <arg>--serialnumber=<replaceable>string</replaceable></arg> + <arg>--maskedinterfaces=<replaceable>XXXXXXXX</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-usbfilter-modify"> + <command>VBoxManage usbfilter modify</command> + <arg choice="req"><replaceable>index</replaceable>,0-<replaceable>N</replaceable></arg> + <arg choice="req">--target=<group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + <arg choice="plain">global</arg> + </group></arg> + <arg>--name=<replaceable>string</replaceable></arg> + <arg>--action=ignore | hold</arg> + <arg>--active=yes | no</arg> + <arg>--vendorid=<replaceable>XXXX</replaceable> | ""</arg> + <arg>--productid=<replaceable>XXXX</replaceable> | ""</arg> + <arg>--revision=<replaceable>IIFF</replaceable> | ""</arg> + <arg>--manufacturer=<replaceable>string</replaceable> | ""</arg> + <arg>--product=<replaceable>string</replaceable> | ""</arg> + <arg>--port=<replaceable>hex</replaceable></arg> + <arg>--remote=yes | no</arg> + <arg>--serialnumber=<replaceable>string</replaceable> | ""</arg> + <arg>--maskedinterfaces=<replaceable>XXXXXXXX</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-usbfilter-remove"> + <command>VBoxManage usbfilter remove</command> + <arg choice="req"><replaceable>index</replaceable>,0-<replaceable>N</replaceable></arg> + <arg choice="req">--target=<group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + <arg choice="plain">global</arg> + </group></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage usbfilter</command> command enables you to + manage USB filters for a specific virtual machine (VM), or global + USB filters that affect the entire &product-name; configuration. + </para> + <para> + Global filters are applied before VM-specific filters. This means + that you can use a global filter to prevent devices from being + captured by any VM. + </para> + <para> + Global filters are applied in a particular order. Only the first + filter that fits a device is applied. For example, the first + global filter makes a specific Kingston memory stick device + available while the second filter ignores all Kingston devices. + The result of applying these filters is that the specific Kingston + memory stick is made available to any machine that has the + appropriate filter, but no other Kingston devices are made + available. + </para> + <refsect2> + <title>Common Operand and Options</title> + <variablelist> + <varlistentry> + <term>index,0-<replaceable>N</replaceable></term> + <listitem><para> + Specifies a single integer that indicates the position of + the filter in the list. Zero (<literal>0</literal>) + represents the first position in the list. If a filter + already exists at the specified position, the existing + filter and any existing filters that follow are moved down + the list. Otherwise, the new filter is appended to the + list. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--action=ignore | hold</option></term> + <listitem><para> + Specifies whether to permit VMs access to devices that fit + the filter description (<literal>hold</literal>) or to + deny them access (<literal>ignore</literal>). This option + applies only to global filters. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--active=yes | no</option></term> + <listitem><para> + Specifies whether the USB filter is active or temporarily + disabled. Valid values are <literal>yes</literal>, which + activates the filter, and <literal>no</literal>, which + disables the filter. The default value is + <literal>yes</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--manufacturer=<replaceable>string</replaceable></option></term> + <listitem><para> + Specifies a manufacturer ID filter as a string. The + default value is an empty string (<literal>""</literal>). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--maskedinterfaces=<replaceable>XXXXXXXX</replaceable></option></term> + <listitem><para> + Specifies a masked interface filter that is used to hide + one or more USB interfaces from the guest. The value is a + bit mask where the set bits correspond to the USB + interfaces to hide, or mask off. This feature is supported + on Linux host systems only. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--name=<replaceable>filter-name</replaceable></option></term> + <listitem><para> + Specifies the name of the filter. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--port=<replaceable>hex</replaceable></option></term> + <listitem><para> + Specifies a hub port number filter as a string. The default + value is an empty string (<literal>""</literal>). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--product=<replaceable>string</replaceable></option></term> + <listitem><para> + Specifies a product ID filter as a string. The default + value is an empty string (<literal>""</literal>). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--productid=<replaceable>XXXX</replaceable></option></term> + <listitem><para> + Specifies a product ID filter. The string representation + for an exact match has the form + <replaceable>XXXX</replaceable>, where + <replaceable>X</replaceable> is a hexadecimal digit + including leading zeroes. The default value is an empty string + (<literal>""</literal>). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--remote=yes | no</option></term> + <listitem><para> + Specifies a remote filter that indicates whether the + device is physically connected to a remote VRDE client or + to a local host system. This option applies to VM filters + only. The default value is an empty string + (<literal>""</literal>). + </para><remark> + Why is the default value an empty string when valid values + are <literal>yes</literal> or <literal>no</literal>? + </remark></listitem> + </varlistentry> + <varlistentry> + <term><option>--revision=<replaceable>IIFF</replaceable></option></term> + <listitem><para> + Specifies a revision ID filter. The string representation + for an exact match has the form + <replaceable>IIFF</replaceable>. + <replaceable>I</replaceable> is a decimal digit of the + integer part of the revision. <replaceable>F</replaceable> + is a decimal digit of its fractional part that includes + leading and trailing zeros. The default value is an empty + string (<literal>""</literal>). + </para><para> + To specify a range of revision IDs, ensure that you use + the hexadecimal form so that the revision is stored as a + 16-bit packed BCD value. For example, the + <literal>int:0x0100-0x0199</literal> expression matches + any revision from 1.0 to 1.99, inclusive. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--serialnumber=<replaceable>string</replaceable></option></term> + <listitem><para> + Specifies a serial number filter as a string. The default + value is an empty string (<literal>""</literal>). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--target=<replaceable>uuid</replaceable> | <replaceable>vmname</replaceable> | global</option></term> + <listitem><para> + Specifies the VM that the filter is attached to. You can + specify the Universally Unique Identifier (UUID) or the + name of the VM. To apply the filter description to all + VMs, specify <literal>global</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vendorid=<replaceable>XXXX</replaceable></option></term> + <listitem><para> + Specifies a vendor ID filter, which is a string + representation of a four-digit hexadecimal number. + <replaceable>X</replaceable> is the hexadecimal digit + including leading zeroes. The default value is an empty + string (<literal>""</literal>). + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-usbfilter-add"> + <title>Add a USB Filter or a Global Filter</title> + <remark role="help-copy-synopsis"/> + <para> + Use the <command>VBoxManage usbfilter add</command> command to + create a new USB filter. + </para> + <para> + In addition, specify parameters by which to filter. You can use + the <command>VBoxManage list usbhost</command> command to view + the parameters for devices that are attached to your system. + </para> + </refsect2> + <refsect2 id="vboxmanage-usbfilter-modify"> + <title>Modify a USB Filter or a Global Filter</title> + <remark role="help-copy-synopsis"/> + <para> + Use the <command>VBoxManage usbfilter modify</command> command + to modify a USB filter. You can use the <command>VBoxManage list + usbfilters</command> command to list global filter indexes and + the <command>VBoxManage showvminfo</command> command to list + indexes for a specific machine. + </para> + </refsect2> + <refsect2 id="vboxmanage-usbfilter-remove"> + <title>Remove a USB Filter or a Global Filter</title> + <remark role="help-copy-synopsis"/> + <para> + Use the <command>VBoxManage usbfilter remove</command> command + to remove a USB filter entry. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command lists the available USB devices on the host + system. + </para> +<screen>$ VBoxManage list usbhost</screen> + <para> + The following command adds a USB filter called + <filename>filter01</filename> to the <filename>ol7</filename> VM. + The filter specifies a Kingston DataTraveler memory stick and is + placed first in the list of USB filters for the VM. + </para> +<screen>$ VBoxManage usbfilter add 0 --target ol7 --name filter01 --vendorid 0x0930 --productid 0x6545</screen> + <para> + The following command removes the USB filter that is second in the + list for the <filename>ol7</filename> VM. + </para> +<screen>$ VBoxManage usbfilter remove 1 --target ol7</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_vboximg-mount.xml b/doc/manual/en_US/man_vboximg-mount.xml new file mode 100644 index 00000000..981ed9cc --- /dev/null +++ b/doc/manual/en_US/man_vboximg-mount.xml @@ -0,0 +1,409 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: vboximg-mount +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="man_vboximg-mount" lang="en"> + <refentryinfo> + <pubdate>November 2019</pubdate> + <title>vboximg-mount</title> + </refentryinfo> + + <refmeta> + <refentrytitle>vboximg-mount</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>vboximg-mount</refname> + <refpurpose>FUSE mount a virtual disk image for Mac OS and Linux hosts</refpurpose> + <refclass>Oracle VM VirtualBox</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboximg-mount-help"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>vboximg-mount</command> + <group choice="req"> + <arg choice="plain">-?</arg> + <arg choice="plain">-h</arg> + <arg choice="plain">--help</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboximg-mount-mount"> + <command>vboximg-mount</command> + <arg choice="req">--image=<replaceable>image-UUID</replaceable></arg> + <arg>--guest-filesystem</arg> + <arg>-o=<replaceable>FUSE-option</replaceable>[,<replaceable>FUSE-option</replaceable>]</arg> + <arg>--root</arg> + <arg>--rw</arg> + <arg choice="req"><replaceable>mountpoint</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboximg-mount-list"> + <command>vboximg-mount</command> + <arg choice="req">--list</arg> + <arg>--image=<replaceable>image-UUID</replaceable></arg> + <arg>--guest-filesystem</arg> + <arg>--verbose</arg> + <arg>--vm=<replaceable>vm-UUID</replaceable></arg> + <arg>--wide</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1 id="vboximg-mount-intro"> + <title>Description</title> + <para> + The <command>vboximg-mount</command> command enables you to make + &product-name; disk images available to a Mac OS or Linux host + operating system (OS) for privileged or non-priviliged access. You + can mount any version of the disk from its available history of + snapshots. Use this command to mount, view, and optionally modify + the contents of an &product-name; virtual disk image, and you can + also use this command to view information about registered virtual + machines (VMs). + </para> + <para> + This command uses the Filesystem in Userspace (FUSE) technology to + provide raw access to an &product-name; virtual disk image. + </para> + <para> + When you use the <option>--image</option> option to specify a base + image identifier, only the base image is mounted. Any related + snapshots are disregarded. Alternatively, if you use the + <option>--image</option> option to specify a snapshot, the state + of the FUSE-mounted virtual disk is synthesized from the implied + chain of snapshots, including the base image. + </para> + <para> + The <command>vboximg-mount</command> command includes experimental + read-only access to file systems inside a VM disk image. This + feature enables you to extract some files from the VM disk image + without starting the VM and without requiring third-party file + system drivers on the host system. &product-name; supports the + FAT, NTFS, <filename>ext2</filename>, <filename>ext3</filename>, + and <filename>ext4</filename> file systems. + </para> + <para> + The virtual disk is exposed as a device node within a FUSE-based + file system that overlays the specified mount point. + </para> + <para> + The FUSE file system includes a directory that contains a number + of files. The file system can also contain a directory that + includes a symbolic link that has the same base name (see the + <command>basename</command>(1) man page) as the virtual disk base + image and points to the location of the virtual disk base image. + The directory can be of the following types: + </para> + <itemizedlist> + <listitem><para> + <filename>vhdd</filename> provides access to the raw disk + image data as a flat image + </para></listitem> + <listitem><para> + <literal>vol<replaceable>ID</replaceable></literal> provides + access to an individual volume on the specified disk image + </para></listitem> + <listitem><para> + <literal>fs<replaceable>ID</replaceable></literal> provides + access to a supported file system without requiring a host + file system driver + </para></listitem> + </itemizedlist> + <refsect2 id="vboximg-mount-help"> + <title>General Command Options</title> + <remark role="help-copy-synopsis"/> + <para> + Use the following options to obtain information about the + <command>vboximg-mount</command> command and its options. + </para> + <variablelist> + <varlistentry> + <term><option>--help</option>, <option>--h</option>, or<option>--?</option></term> + <listitem><para> + Shows usage information. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboximg-mount-mount"> + <title>Mounting an &product-name; Disk Image</title> + <remark role="help-copy-synopsis"/> + <para> + Use the <command>vboximg-mount</command> command to mount an + &product-name; virtual disk image on a Mac OS or Linux host + system. When mounted, you can view the contents of the disk + image or modify the contents of the disk image. + </para> + <para> + You can use the <command>vboximg-mount</command> command to + restrict FUSE-based access to a subsection of the virtual disk. + </para> + <variablelist> + <varlistentry> + <term><option>--image=<replaceable>disk-image</replaceable></option></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID), name, + or path of the &product-name; disk image. + </para><para> + The short form of the <option>--image</option> option is + <option>-i</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--guest-filesystem</option></term> + <listitem><para> + Enables experimental read-only support for guest file + systems. When you specify this option, all known file + systems are made available to access. + </para><para> + The short form of the <option>--guest-filesystem</option> + option is <option>-g</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>-o=<replaceable>FUSE-option</replaceable>[,<replaceable>FUSE-option</replaceable>...]</option></term> + <listitem><para> + Specifies FUSE mount options. + </para><para> + The <command>vboximg-mount</command> command enables you + to use the FUSE mount options that are described in the + <command>mount.fuse</command>(8) man page. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--root</option></term> + <listitem><para> + Overrides the security measure that restricts file access + to the file system owner by also granting file access to + the <literal>root</literal> user. + </para><para> + Same as the <option>-o allow_root</option> option. See the + <option>-o</option> option description. + </para><para> + This option is incompatible with the <option>-o + allow_other</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--rw</option></term> + <listitem><para> + Mounts the specified image as read-write, which is + required if you want to modify its contents. By default, + images are mounted as read-only. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>mount-point</replaceable></term> + <listitem><para> + Specifies the path name of a directory on which to mount + the &product-name; disk image. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboximg-mount-list"> + <title>Viewing &product-name; Disk Image Information</title> + <remark role="help-copy-synopsis"/> + <para> + Use the <command>vboximg-mount</command> command to view + information about registered VMs or an &product-name; virtual + disk image. + </para> + <variablelist> + <varlistentry> + <term><option>--image=<replaceable>disk-image</replaceable></option></term> + <listitem><para> + Specifies the UUID, name, or path of the &product-name; + disk image. + </para><para> + The short form of the <option>--image</option> option is + <option>-i</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--guest-filesystem</option></term> + <listitem><para> + Enables experimental read-only support for guest file + systems. When you specify this option, all known file + systems are made available to access. + </para><para> + The short form of the <option>--guest-filesystem</option> + option is <option>-g</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--list</option></term> + <listitem><para> + Shows information about the disks that are associated with + the registered VMs. If you specify a disk image, this + option shows information about the partitions of the + specified image. + </para><para> + When you specify the <option>--verbose</option> option, + the output includes detailed information about the VMs and + media, including snapshot images and file paths. + </para><para> + The short form of the <option>--list</option> option is + <option>-l</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--verbose</option></term> + <listitem><para> + Shows or logs detailed information. + </para><para> + The short form of the <option>--verbose</option> option is + <option>-v</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vm=<replaceable>vm-UUID</replaceable></option></term> + <listitem><para> + Outputs information about the VM that is associated with + the specified UUID. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--wide</option></term> + <listitem><para> + Outputs information in a wide format. This output includes + the lock state information of running VMs. For VMs that + are not running, the state is <literal>created</literal>. + </para><para> + The wide output uses a tree-like structure in the VM + column to show the relationship between a VM base image + and its snapshots. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="MOUNT-MOUNT,MOUNT-LIST"/> + <para> + The following example shows how to mount a virtual disk image on + the host operating system (OS). + </para> +<screen>$ mkdir fuse_mount_point +$ vboximg-mount --image=b490e578-08be-4f7d-98e9-4c0ef0952377 fuse_mount_point +$ ls fuse_mount_point +ubu.vdi[32256:2053029880] vhdd +$ sudo mount fuse_mount_point/vhdd /mnt</screen> + <para> + The <command>mkdir</command> command creates a mount point called + <filename>fuse_mount_point</filename> on the host OS. The + <command>vboximg-mount</command> command is then used to mount the + specified disk image on the <filename>fuse_mount_point</filename> + mount point. The mount includes all snapshots for the disk image. + </para> + <para> + The <command>ls</command> command shows the contents of + <filename>fuse_mount_point</filename>. The + <command>mount</command> command is then used to mount the + FUSE-mounted device node, <command>vhdd</command>, on the + <filename>/mnt</filename> mount point. The <command>vhdd</command> + device node represents the virtual disk image. + </para> + <para> + The following example shows how to make the known file systems of + the <literal>b490e578-08be-4f7d-98e9-4c0ef0952377</literal> disk + image accessible when the image is mounted on the + <filename>fuse_mount_point</filename> mount point: + </para> +<screen>$ vboximg-mount --image=b490e578-08be-4f7d-98e9-4c0ef0952377 \ +--guest-filesystem fuse_mount_point +</screen> + <para> + The following command outputs detailed information about all + registered VMs and their snapshots: + </para> +<screen>$ vboximg-mount --list --verbose</screen> + <para> + The following command shows an excerpt of the list output in wide + format. + </para> +<screen>$ vboximg-mount --list --wide + +VM Image Size Type State UUID (hierarchy) +------------------------------------------ ------------------------------------ +Proxy 0833f5bc-6304-42e1-b799-cdc81c576c60 + | + +- Proxy.vdi 4.8G VDI rlock d5f84afb-0794-4952-ab71-6bbcbee07737 + | +- <snapshot> 12.3G VDI rlock dffc67aa-3023-477f-8033-b27e3daf4f54 + | +- <snapshot> 8.8G VDI rlock 3b2755bd-5f2a-4171-98fe-647d510b6274 + | +- <snapshot> 14.6G VDI rlock e2ccdb5f-49e8-4123-8623-c61f363cc5cf + | +- <snapshot> 7.4G VDI wlock 3c1e6794-9091-4be3-9e80-11aba40c2649 + +------------------------------------------ ------------------------------------ +Oracle Linux 7 5365ab5f-470d-44c0-9863-dad532ee5905 + | + +- Oracle Linux 7.vdi 7.0G VDI created 96d2e92e-0d4e-46ab-a0f1-008fdbf997e7 + | +- <snapshot> 15.9G VDI created f9cc866a-9166-42e9-a503-bbfe9b7312e8 + | + +- kernel.vdi 11.1G VDI created 79a370bd-0c4f-480a-30bb-10cdea68423f +</screen> + <para> + The output shows that the Proxy VM is running the fourth snapshot + of the <command>Proxy.vdi</command> virtual disk image. The + running state is indicated by the <command>wlock</command> value + in the State column. + </para> + <para> + The Oracle Linux 7 VM is not running. It has two images: + <command>Oracle Linux 7.vdi</command> and + <command>kernel.vdi</command>. The <command>Oracle Linux + 7.vdi</command> image has a snapshot. + </para> + <para> + The following command shows information about the VM with the + specified UUID: + </para> +<screen> +$ vboximg-mount --list --vm=b1d5563b-2a5b-4013-89f1-26c81d6bbfa0 +----------------------------------------------------------------- +VM: ubu +UUID: b1d5563b-2a5b-4013-89f1-26c81d6bbfa0 + + Image: ubu.vdi + UUID: b490e578-08be-4f7d-98e9-4c0ef0952377 + + Snapshot: 35afe1e0-0a51-44f3-a228-caf172f3306f + Size: 12.1G + + Snapshot: 874279c1-4425-4282-ada8-a9c07c00bbf9 + Size: 13.6G + + Image: kernel.vdi + UUID: 79a370bd-6eb7-4dbf-8bc6-d29118f127e0</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/oracle-accessibility-ohc-en.xml b/doc/manual/en_US/oracle-accessibility-ohc-en.xml new file mode 100644 index 00000000..cdebe716 --- /dev/null +++ b/doc/manual/en_US/oracle-accessibility-ohc-en.xml @@ -0,0 +1,16 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE simplesect PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" + +[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<simplesect id="access-doc-access"> + <title>Documentation Accessibility</title> + <para>For information about Oracle's commitment to accessibility, visit the Oracle Accessibility + Program website at <ulink url="https://www.oracle.com/corporate/accessibility/"/>. </para> + <para>For information about the accessibility of the Oracle Help Center, see the Oracle + Accessibility Conformance Report at <ulink + url="https://www.oracle.com/corporate/accessibility/templates/t2-11535.html"/>.</para> +</simplesect> diff --git a/doc/manual/en_US/oracle-diversity.xml b/doc/manual/en_US/oracle-diversity.xml new file mode 100644 index 00000000..99123727 --- /dev/null +++ b/doc/manual/en_US/oracle-diversity.xml @@ -0,0 +1,14 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE simplesect PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://docbook.org/xml/4.5/docbookx.dtd"> +<simplesect> + <title>Diversity and Inclusion</title> + <para>Oracle is fully committed to diversity and inclusion. Oracle respects and values having a + diverse workforce that increases thought leadership and innovation. As part of our + initiative to build a more inclusive culture that positively impacts our employees, + customers, and partners, we are working to remove insensitive terms from our products and + documentation. We are also mindful of the necessity to maintain compatibility with our + customers' existing technologies and the need to ensure continuity of service as Oracle's + offerings and industry standards evolve. Because of these technical constraints, our effort + to remove insensitive terms is ongoing and will take time and external cooperation.</para> +</simplesect> diff --git a/doc/manual/en_US/oracle-support-en.xml b/doc/manual/en_US/oracle-support-en.xml new file mode 100644 index 00000000..09b64007 --- /dev/null +++ b/doc/manual/en_US/oracle-support-en.xml @@ -0,0 +1,27 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE simplesect PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" +[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<simplesect> + + <!-- Include this statement in the document Preface --> + + <title>Access to Oracle Support</title> + + <para> + Oracle customers that have purchased support have access to + electronic support through My Oracle Support. For information, visit + +<?fo-linebreak?> + + <ulink url="http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info">http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info</ulink> + or visit + <ulink + url="http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs">http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs</ulink> + if you are hearing impaired. + </para> + +</simplesect> diff --git a/doc/manual/en_US/user_AdvancedTopics.xml b/doc/manual/en_US/user_AdvancedTopics.xml new file mode 100644 index 00000000..bc7c5e5e --- /dev/null +++ b/doc/manual/en_US/user_AdvancedTopics.xml @@ -0,0 +1,7676 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="AdvancedTopics"> + + <title>Advanced Topics</title> + + <sect1 id="autologon"> + + <title>Automated Guest Logins</title> + + <para> + &product-name; provides Guest Addition modules for Windows, Linux, + and Oracle Solaris to enable automated logins on the guest. + </para> + + <para> + When a guest operating system is running in a virtual machine, it + might be desirable to perform coordinated and automated logins + using credentials passed from the host. Credentials are user name, + password, and domain name, where each value might be empty. + </para> + + <sect2 id="autologon_win"> + + <title>Automated Windows Guest Logins</title> + + <para> + Windows provides a modular system login subsystem, called + Winlogon, which can be customized and extended by means of + so-called GINA (Graphical Identification and Authentication) + modules. In Windows Vista and later releases, the GINA modules + were replaced with a new mechanism called credential providers. + The &product-name; Guest Additions for Windows come with both, a + GINA and a credential provider module, and therefore enable any + Windows guest to perform automated logins. + </para> + + <para> + To activate the &product-name; GINA or credential provider + module, install the Guest Additions using the command line + switch <option>/with_autologon</option>. All the following + manual steps required for installing these modules will be then + done by the installer. + </para> + + <para> + To manually install the &product-name; GINA module, extract the + Guest Additions as shown in + <xref linkend="windows-guest-file-extraction" />, and copy the + <filename>VBoxGINA.dll</filename> file to the Windows + <filename>SYSTEM32</filename> directory. In the registry, create + the following key with a value of + <filename>VBoxGINA.dll</filename>: + </para> + +<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GinaDLL</screen> + + <note> + <para> + The &product-name; GINA module is implemented as a wrapper + around the <filename>MSGINA.DLL</filename> standard Windows + GINA module. As a result, it might not work correctly with + third-party GINA modules. + </para> + </note> + + <para> + To manually install the &product-name; credential provider + module, extract the Guest Additions as shown in + <xref linkend="windows-guest-file-extraction" /> and copy the + <filename>VBoxCredProv.dll</filename> file to the Windows + <filename>SYSTEM32</filename> directory. In the registry, create + the following keys: + </para> + +<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\ +Authentication\Credential Providers\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B} + +HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B} + +HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32</screen> + + <para> + All default values, the key named <literal>Default</literal>, + must be set to <literal>VBoxCredProv</literal>. + </para> + + <para> + Create the following string and assign it a value of + <literal>Apartment</literal>. + </para> + +<screen>HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32\ThreadingModel</screen> + + <para> + To set credentials, use the following command on a + <emphasis>running</emphasis> VM: + </para> + +<screen>$ VBoxManage controlvm "Windows XP" setcredentials "John Doe" "secretpassword" "DOMTEST"</screen> + + <para> + While the VM is running, the credentials can be queried by the + &product-name; login modules, GINA or credential provider, using + the &product-name; Guest Additions device driver. When Windows + is in <emphasis>logged out</emphasis> mode, the login modules + will constantly poll for credentials and if they are present, a + login will be attempted. After retrieving the credentials, the + login modules will erase them so that the above command will + have to be repeated for subsequent logins. + </para> + + <para> + For security reasons, credentials are not stored in any + persistent manner and will be lost when the VM is reset. Also, + the credentials are write-only. There is no way to retrieve the + credentials from the host side. Credentials can be reset from + the host side by setting empty values. + </para> + + <para> + Depending on the Windows guest version, the following + restrictions apply: + </para> + + <itemizedlist> + + <listitem> + <para> + For <emphasis role="bold">Windows XP guests.</emphasis> The + login subsystem needs to be configured to use the classic + login dialog, as the &product-name; GINA module does not + support the Windows XP-style welcome dialog. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Windows Vista, Windows 7, Windows 8, + and Windows 10 guests.</emphasis> The login subsystem does + not support the so-called Secure Attention Sequence, + <literal>Ctrl+Alt+Del</literal>. As a result, the guest's + group policy settings need to be changed to not use the + Secure Attention Sequence. Also, the user name given is only + compared to the true user name, not the user friendly name. + This means that when you rename a user, you still have to + supply the original user name as Windows never renames user + accounts internally. + </para> + </listitem> + + <listitem> + <para> + Automatic login handling of the built-in + <emphasis role="bold">Windows Remote Desktop + Service</emphasis>, formerly known as Terminal Services, is + disabled by default. To enable it, create the following + registry key with a <literal>DWORD</literal> value of + <literal>1</literal>. + </para> + +<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\VirtualBox Guest Additions\AutoLogon</screen> + </listitem> + + </itemizedlist> + + <para> + The following command forces &product-name; to keep the + credentials after they were read by the guest and on VM reset: + </para> + +<screen>$ VBoxManage setextradata "Windows XP" VBoxInternal/Devices/VMMDev/0/Config/KeepCredentials 1</screen> + + <para> + Note that this is a potential security risk, as a malicious + application running on the guest could request this information + using the proper interface. + </para> + + </sect2> + + <sect2 id="autologon_unix"> + + <title>Automated Linux and UNIX Guest Logins</title> + + <para> + &product-name; provides a custom PAM module (Pluggable + Authentication Module) which can be used to perform automated + guest logins on platforms which support this framework. + Virtually all modern Linux and UNIX distributions rely on PAM. + </para> + + <para> + For automated logins on Ubuntu, or Ubuntu-derived, distributions + using LightDM as the display manager. See + <xref linkend="autologon_unix_lightdm" />. + </para> + + <para> + The <filename>pam_vbox.so</filename> module itself + <emphasis>does not</emphasis> do an actual verification of the + credentials passed to the guest OS. Instead it relies on other + modules such as <filename>pam_unix.so</filename> or + <filename>pam_unix2.so</filename> down in the PAM stack to do + the actual validation using the credentials retrieved by + <filename>pam_vbox.so</filename>. Therefore + <filename>pam_vbox.so</filename> has to be on top of the + authentication PAM service list. + </para> + + <note> + <para> + The <filename>pam_vbox.so</filename> module only supports the + <literal>auth</literal> primitive. Other primitives such as + <literal>account</literal>, <literal>session</literal>, or + <literal>password</literal> are not supported. + </para> + </note> + + <para> + The <filename>pam_vbox.so</filename> module is shipped as part + of the Guest Additions but it is not installed and/or activated + on the guest OS by default. In order to install it, it has to be + copied from + <filename>/opt/VBoxGuestAdditions-<replaceable>version</replaceable>/other/</filename> + to the security modules directory. This is usually + <filename>/lib/security/</filename> on 32-bit Linux guests or + <filename>/lib64/security/</filename> on 64-bit Linux guests. + Please refer to your guest OS documentation for the correct PAM + module directory. + </para> + + <para> + For example, to use <filename>pam_vbox.so</filename> with a + Ubuntu Linux guest OS and the GNOME Desktop Manager (GDM) to log + in users automatically with the credentials passed by the host, + configure the guest OS as follows: + </para> + + <orderedlist> + + <listitem> + <para> + Copy the <filename>pam_vbox.so</filename> module to the + security modules directory. In this case, + <filename>/lib/security</filename>. + </para> + </listitem> + + <listitem> + <para> + Edit the PAM configuration file for GDM, found at + <filename>/etc/pam.d/gdm</filename>. Add the line + <literal>auth requisite pam_vbox.so</literal> at the top. + Additionally, in most Linux distributions there is a file + called <filename>/etc/pam.d/common-auth</filename>. This + file is included in many other services, like the GDM file + mentioned above. There you also have to add the line + <literal>auth requisite pam_vbox.so</literal>. + </para> + </listitem> + + <listitem> + <para> + If authentication against the shadow database using + <filename>pam_unix.so</filename> or + <filename>pam_unix2.so</filename> is desired, the argument + <literal>try_first_pass</literal> for + <filename>pam_unix.so</filename> or + <literal>use_first_pass</literal> for + <filename>pam_unix2.so</filename> is needed in order to pass + the credentials from the &product-name; module to the shadow + database authentication module. For Ubuntu, this needs to be + added to <filename>/etc/pam.d/common-auth</filename>, to the + end of the line referencing + <filename>pam_unix.so</filename>. This argument tells the + PAM module to use credentials already present in the stack, + such as the ones provided by the &product-name; PAM module. + </para> + </listitem> + + </orderedlist> + + <warning> + <para> + An incorrectly configured PAM stack can effectively prevent + you from logging into your guest system. + </para> + </warning> + + <para> + To make deployment easier, you can pass the argument + <literal>debug</literal> right after the + <filename>pam_vbox.so</filename> statement. Debug log output + will then be recorded using syslog. + </para> + + <note> + <para> + By default, <command>pam_vbox</command> does not wait for + credentials to arrive from the host. When a login prompt is + shown, for example by GDM/KDM or the text console, and + <command>pam_vbox</command> does not yet have credentials it + does not wait until they arrive. Instead the next module in + the PAM stack, depending on the PAM configuration, will have + the chance for authentication. + </para> + </note> + + <para> + <command>pam_vbox</command> supports various guest property + parameters that are located in + <filename>/VirtualBox/GuestAdd/PAM/</filename>. These parameters + allow <command>pam_vbox</command> to wait for credentials to be + provided by the host and optionally can show a message while + waiting for those. The following guest properties can be set: + </para> + + <itemizedlist> + + <listitem> + <para> + <literal>CredsWait</literal>: Set to 1 if + <command>pam_vbox</command> should start waiting until + credentials arrive from the host. Until then no other + authentication methods such as manually logging in will be + available. If this property is empty or gets deleted no + waiting for credentials will be performed and + <command>pam_vbox</command> will act like before. This + property must be set read-only for the guest + (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + <listitem> + <para> + <literal>CredsWaitAbort</literal>: Aborts waiting for + credentials when set to any value. Can be set from host and + the guest. + </para> + </listitem> + + <listitem> + <para> + <literal>CredsWaitTimeout</literal>: Timeout, in seconds, to + let <command>pam_vbox</command> wait for credentials to + arrive. When no credentials arrive within this timeout, + authentication of <command>pam_vbox</command> will be set to + failed and the next PAM module in chain will be asked. If + this property is not specified, set to 0 or an invalid + value, an infinite timeout will be used. This property must + be set read-only for the guest + (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + </itemizedlist> + + <para> + To customize <command>pam_vbox</command> further there are the + following guest properties: + </para> + + <itemizedlist> + + <listitem> + <para> + <literal>CredsMsgWaiting</literal>: Custom message showed + while pam_vbox is waiting for credentials from the host. + This property must be set read-only for the guest + (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + <listitem> + <para> + <literal>CredsMsgWaitTimeout</literal>: Custom message + showed when waiting for credentials by + <command>pam_vbox</command> has timed out. For example, they + did not arrive within time. This property must be set + read-only for the guest (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + </itemizedlist> + + <note> + <para> + If a <command>pam_vbox</command> guest property does not have + the correct flag set (<literal>RDONLYGUEST</literal>) the + property is ignored and, depending on the property, a default + value will be used. This can result in pam_vbox not waiting + for credentials. Consult the appropriate syslog file for more + information and use the <literal>debug</literal> option. + </para> + </note> + + <sect3 id="autologon_unix_lightdm"> + + <title>&product-name; Greeter for Ubuntu/LightDM</title> + + <para> + &product-name; comes with a greeter module, named + <command>vbox-greeter</command>, that can be used with + LightDM. LightDM is the default display manager for Ubuntu + Linux and therefore can also be used for automated guest + logins. + </para> + + <para> + <command>vbox-greeter</command> does not need the + <command>pam_vbox</command> module described in + <xref linkend="autologon_unix"/>in order to function. It comes + with its own authentication mechanism provided by LightDM. + However, to provide maximum flexibility both modules can be + used together on the same guest. + </para> + + <para> + As with the <command>pam_vbox</command> module, + <command>vbox-greeter</command> is shipped as part of the + Guest Additions but it is not installed or activated on the + guest OS by default. To install + <command>vbox-greeter</command> automatically upon Guest + Additions installation, use the + <option>--with-autologon</option> option when starting the + <command>VBoxLinuxAdditions.run</command> file: + </para> + +<screen># ./VBoxLinuxAdditions.run -- --with-autologon</screen> + + <para> + For manual or postponed installation, copy the + <filename>vbox-greeter.desktop</filename> file from + <filename>/opt/VBoxGuestAdditions-<version>/other/</filename> + to the <filename>xgreeters</filename> directory, which is + usually <filename>/usr/share/xgreeters/</filename>. See your + guest OS documentation for the name of the correct LightDM + greeter directory. + </para> + + <para> + The <command>vbox-greeter</command> module is installed by the + &product-name; Guest Additions installer and is located in + <filename>/usr/sbin/</filename>. To enable + <command>vbox-greeter</command> as the standard greeter + module, edit the file + <filename>/etc/lightdm/lightdm.conf</filename> as follows: + </para> + +<screen>[SeatDefaults] +greeter-session=vbox-greeter</screen> + + <note> + <itemizedlist> + + <listitem> + <para> + The LightDM server must be fully restarted in order for + <command>vbox-greeter</command> to be used as the + default greeter. As <literal>root</literal> on Ubuntu, + run <command>service lightdm --full-restart</command> or + restart the guest. + </para> + </listitem> + + <listitem> + <para> + <command>vbox-greeter</command> is independent of the + graphical session you choose, such as Gnome, KDE, or + Unity. However, <command>vbox-greeter</command> does + require FLTK 1.3 or later to implement its own user + interface. + </para> + </listitem> + + </itemizedlist> + </note> + + <para> + There are numerous guest properties which can be used to + further customize the login experience. For automatically + logging in users, the same guest properties apply as for + <command>pam_vbox</command>. See + <xref linkend="autologon_unix" />. + </para> + + <para> + In addition to the previously mentioned guest properties, + <command>vbox-greeter</command> enables you to further + customize its user interface. The following guest properties + are located in the + <filename>/VirtualBox/GuestAdd/Greeter/</filename> directory: + </para> + + <itemizedlist> + + <listitem> + <para> + <literal>HideRestart</literal>: Set to 1 if + <command>vbox-greeter</command> should hide the button to + restart the guest. This property must be set read-only for + the guest (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + <listitem> + <para> + <literal>HideShutdown</literal>: Set to 1 if + <command>vbox-greeter</command> should hide the button to + shutdown the guest. This property must be set read-only + for the guest (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + <listitem> + <para> + <literal>BannerPath</literal>: Path to a + <filename>.PNG</filename> file to use as a banner image on + the top of the greeter. The image size must be 460 x 90 + pixels, any bit depth. This property must be set read-only + for the guest (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + <listitem> + <para> + <literal>UseTheming</literal>: Set to 1 for turning on the + following theming options. This property must be set + read-only for the guest (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + <listitem> + <para> + <literal>Theme/BackgroundColor</literal>: Hexadecimal + RRGGBB color for the background. This property must be set + read-only for the guest (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + <listitem> + <para> + <literal>Theme/LogonDialog/HeaderColor</literal>: + Hexadecimal RRGGBB foreground color for the header text. + This property must be set read-only for the guest + (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + <listitem> + <para> + <literal>Theme/LogonDialog/BackgroundColor</literal>: + Hexadecimal RRGGBB color for the login dialog background. + This property must be set read-only for the guest + (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + <listitem> + <para> + <literal>Theme/LogonDialog/ButtonColor</literal>: + Hexadecimal RRGGBB background color for the login dialog + button. This property must be set read-only for the guest + (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + </itemizedlist> + + <note> + <para> + The same restrictions for the guest properties above apply + as for the ones specified in the <literal>pam_vbox</literal> + section. + </para> + </note> + + </sect3> + + </sect2> + + </sect1> + + <sect1 id="adv-config-win-guest"> + + <title>Advanced Configuration for Windows Guests</title> + + <sect2 id="sysprep"> + + <title>Automated Windows System Preparation</title> + + <para> + Microsoft offers a system preparation tool called Sysprep, to + prepare a Windows system for deployment or redistribution. Some + Windows releases include Sysprep on the installation medium, but + the tool is also available for download from the Microsoft web + site. In a standard For most Windows versions, Sysprep is + included in a default installation. Sysprep mainly consists of + an executable called <command>sysprep.exe</command> which is + invoked by the user to put the Windows installation into + preparation mode. + </para> + + <para> + The Guest Additions offer a way to launch a system preparation + on the guest operating system in an automated way, controlled + from the host system. See + <xref linkend="guestadd-guestcontrol" /> for details of how to + use this feature with the special identifier + <literal>sysprep</literal> as the program to execute, along with + the user name <literal>sysprep</literal> and password + <literal>sysprep</literal> for the credentials. Sysprep is then + started with the required system rights. + </para> + + <note> + <para> + Specifying the location of <command>sysprep.exe</command> is + <emphasis role="bold">not possible</emphasis>. Instead the + following paths are used, based on the Windows release: + </para> + + <itemizedlist> + + <listitem> + <para> + <filename>C:\sysprep\sysprep.exe</filename> for Windows XP + and earlier + </para> + </listitem> + + <listitem> + <para> + <filename>%WINDIR%\System32\sysprep\sysprep.exe</filename> + for Windows Vista and later + </para> + </listitem> + + </itemizedlist> + + <para> + The Guest Additions will automatically use the appropriate + path to execute the system preparation tool. + </para> + </note> + + </sect2> + + </sect1> + + <sect1 id="adv-config-linux-guest"> + + <title>Advanced Configuration for Linux and Oracle Solaris Guests</title> + + <sect2 id="linux-guest-manual-setup"> + + <title>Manual Setup of Selected Guest Services on Linux</title> + + <para> + The &product-name; Guest Additions contain several different + drivers. If you do not want to configure them all, use the + following command to install the Guest Additions: + </para> + +<screen>$ sh ./VBoxLinuxAdditions.run no_setup</screen> + + <para> + After running this script, run the <command>rcvboxadd + setup</command> command as <literal>root</literal> to compile + the kernel modules. + </para> + + <para> + On some 64-bit guests, you must replace <filename>lib</filename> + with <filename>lib64</filename>. On older guests that do not run + the <command>udev</command> service, you must add the + <command>vboxadd</command> service to the default runlevel to + ensure that the modules are loaded. + </para> + + <para> + To set up the time synchronization service, add the + <command>vboxadd-service</command> service to the default + runlevel. To set up the X11 and OpenGL part of the Guest + Additions, run the <command>rcvboxadd-x11 setup</command> + command. Note that you do not need to enable additional + services. + </para> + + <para> + Use the <command>rcvboxadd setup</command> to recompile the + guest kernel modules. + </para> + + <para> + After compilation, reboot your guest to ensure that the new + modules are loaded. + </para> + + </sect2> + + <sect2 id="guestxorgsetup"> + + <title>Guest Graphics and Mouse Driver Setup in Depth</title> + + <para> + This section assumes that you are familiar with configuring the + X.Org server using xorg.conf and optionally the newer mechanisms + using hal or udev and xorg.conf.d. If not you can learn about + them by studying the documentation which comes with X.Org. + </para> + + <para> + The &product-name; Guest Additions includes drivers for X.Org. + By default these drivers are in the following directory: + </para> + + <para> + <filename>/opt/VBoxGuestAdditions-<replaceable>version</replaceable>/other/</filename> + </para> + + <para> + The correct versions for the X server are symbolically linked + into the X.Org driver directories. + </para> + + <para> + For graphics integration to work correctly, the X server must + load the <literal>vboxvideo</literal> driver. Many recent X + server versions look for it automatically if they see that they + are running in &product-name;. For an optimal user experience, + the guest kernel drivers must be loaded and the Guest Additions + tool <command>VBoxClient</command> must be running as a client + in the X session. + </para> + + <para> + For mouse integration to work correctly, the guest kernel + drivers must be loaded. In addition, for legacy X servers the + correct <literal>vboxmouse</literal> driver must be loaded and + associated with <filename>/dev/mouse</filename> or + <filename>/dev/psaux</filename>. For most guests, a driver for a + PS/2 mouse must be loaded and the correct vboxmouse driver must + be associated with <filename>/dev/vboxguest</filename>. + </para> + + <para> + The &product-name; guest graphics driver can use any graphics + configuration for which the virtual resolution fits into the + virtual video memory allocated to the virtual machine, minus a + small amount used by the guest driver, as described in + <xref linkend="settings-display" />. The driver will offer a + range of standard modes at least up to the default guest + resolution for all active guest monitors. The default mode can + be changed by setting the output property VBOX_MODE to + "<width>x<height>" for any guest monitor. When + VBoxClient and the kernel drivers are active this is done + automatically when the host requests a mode change. The driver + for older versions can only receive new modes by querying the + host for requests at regular intervals. + </para> + + <para> + With legacy X Servers before version 1.3, you can also add your + own modes to the X server configuration file. Add them to the + "Modes" list in the "Display" subsection of the "Screen" + section. For example, the following section has a custom + 2048x800 resolution mode added: + </para> + +<screen>Section "Screen" + Identifier "Default Screen" + Device "VirtualBox graphics card" + Monitor "Generic Monitor" + DefaultDepth 24 + SubSection "Display" + Depth 24 + Modes "2048x800" "800x600" "640x480" + EndSubSection +EndSection</screen> + + </sect2> + + </sect1> + + <sect1 id="cpuhotplug"> + + <title>CPU Hot-Plugging</title> + + <para> + With virtual machines running modern server operating systems, + &product-name; supports CPU hot-plugging. + </para> + + <para> + On a physical computer CPU hot-plugging would mean that a CPU can + be added or removed while the machine is running. &product-name; + supports adding and removing of virtual CPUs while a virtual + machine is running. + </para> + + <para> + CPU hot-plugging works only with guest operating systems that + support the feature. So far this applies only to Linux and Windows + Server. Windows supports only hot-add, while Linux supports + hot-add and hot-remove. To use this feature with more than 8 CPUs, + a 64-bit Linux guest is required. + </para> + + <para> + CPU hot-plugging is done using the <command>VBoxManage</command> + command-line interface. First, hot-plugging needs to be enabled + for a virtual machine: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --cpu-hotplug on</screen> + + <para> + The <option>--cpus</option> option is used to specify the maximum + number of CPUs that the virtual machine can have: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --cpus 8</screen> + + <para> + When the VM is off, you can then add and remove virtual CPUs with + the <command>VBoxManage modifyvm --plug-cpu</command> and + <command>VBoxManage modifyvm --unplug-cpu</command> commands, + which take the number of the virtual CPU as a parameter, as + follows: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --plug-cpu 3 +$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --unplug-cpu 3</screen> + + <para> + Note that CPU 0 can never be removed. + </para> + + <para> + While the VM is running, CPUs can be added and removed with the + <command>VBoxManage controlvm plugcpu</command> and + <command>VBoxManage controlvm unplugcpu</command> commands + instead, as follows: + </para> + +<screen>$ VBoxManage controlvm <replaceable>VM-name</replaceable> plugcpu 3 +$ VBoxManage controlvm <replaceable>VM-name</replaceable> unplugcpu 3</screen> + + <para> + See <xref linkend="vboxmanage-modifyvm" /> and + <xref linkend="vboxmanage-controlvm" /> for details. + </para> + + <para> + With Linux guests, the following applies: + </para> + + <para> + To prevent ejection while the CPU is still used it has to be + ejected from within the guest before. The Linux Guest Additions + contain a service which receives hot-remove events and ejects the + CPU. Also, after a CPU is added to the VM it is not automatically + used by Linux. The Linux Guest Additions service will take care of + that if installed. If not a CPU can be started with the following + command: + </para> + +<screen>$ echo 1 > /sys/devices/system/cpu/cpu<id>/online</screen> + + </sect1> + +<!--<sect1 id="pcipassthrough"> + + <title>PCI Passthrough</title> + + <para> + When running on Linux hosts with a kernel version later than + <literal>2.6.31</literal>, experimental host PCI devices + passthrough is available. + </para> + + <note> + <para> + The PCI passthrough module is shipped as an &product-name; + extension package, which must be installed separately. See + <xref linkend="intro-installing" />. + </para> + </note> + + <para> + This feature enables a guest to directly use physical PCI devices + on the host, even if host does not have drivers for this + particular device. Both, regular PCI and some PCI Express cards, + are supported. AGP and certain PCI Express cards are not supported + at the moment if they rely on Graphics Address Remapping Table + (GART) unit programming for texture management as it does rather + non-trivial operations with pages remapping interfering with + IOMMU. This limitation may be lifted in future releases. + </para> + + <para> + To be fully functional, PCI passthrough support in &product-name; + depends upon an IOMMU hardware unit. If the device uses bus + mastering, for example it performs DMA to the OS memory on its + own, then an IOMMU is required. Otherwise such DMA transactions + may write to the wrong physical memory address as the device DMA + engine is programmed using a device-specific protocol to perform + memory transactions. The IOMMU functions as translation unit + mapping physical memory access requests from the device using + knowledge of the guest physical address to host physical addresses + translation rules. + </para> + + <para> + Intel's solution for IOMMU is called Intel Virtualization + Technology for Directed I/O (VT-d), and AMD's solution is called + AMD-Vi. Check your motherboard datasheet for the appropriate + technology. Even if your hardware does not have a IOMMU, certain + PCI cards may work, such as serial PCI adapters, but the guest + will show a warning on boot and the VM execution will terminate if + the guest driver will attempt to enable card bus mastering. + </para> + + <para> + It is very common that the BIOS or the host OS disables the IOMMU + by default. So before any attempt to use it please make sure that + the following apply: + </para> + + <itemizedlist> + + <listitem> + <para> + Your motherboard has an IOMMU unit. + </para> + </listitem> + + <listitem> + <para> + Your CPU supports the IOMMU. + </para> + </listitem> + + <listitem> + <para> + The IOMMU is enabled in the BIOS. + </para> + </listitem> + + <listitem> + <para> + The VM must run with VT-x/AMD-V and nested paging enabled. + </para> + </listitem> + + <listitem> + <para> + Your Linux kernel was compiled with IOMMU support, including + DMA remapping. See the <literal>CONFIG_DMAR</literal> kernel + compilation option. The PCI stub driver + (<literal>CONFIG_PCI_STUB</literal>) is required as well. + </para> + </listitem> + + <listitem> + <para> + Your Linux kernel recognizes and uses the IOMMU unit. The + <literal>intel_iommu=on</literal> boot option could be needed. + Search for DMAR and PCI-DMA in kernel boot log. + </para> + </listitem> + + </itemizedlist> + + <para> + Once you made sure that the host kernel supports the IOMMU, the + next step is to select the PCI card and attach it to the guest. To + figure out the list of available PCI devices, use the + <command>lspci</command> command. The output will look as follows: + </para> + +<screen>01:00.0 VGA compatible controller: ATI Technologies Inc Cedar PRO [Radeon HD 5450] +01:00.1 Audio device: ATI Technologies Inc Manhattan HDMI Audio [Mobility Radeon HD 5000 Series] +02:00.0 Ethernet controller: Realtek Semiconductor Co., Ltd. RTL8111/8168B PCI Express Gigabit + Ethernet controller (rev 03) +03:00.0 SATA controller: JMicron Technology Corp. JMB362/JMB363 Serial ATA Controller (rev 03) +03:00.1 IDE interface: JMicron Technology Corp. JMB362/JMB363 Serial ATA Controller (rev 03) +06:00.0 VGA compatible controller: nVidia Corporation G86 [GeForce 8500 GT] (rev a1)</screen> + + <para> + The first column is a PCI address, in the format + <literal><replaceable>bus</replaceable>:<replaceable>device</replaceable>.<replaceable>function</replaceable></literal>. + This address could be used to identify the device for further + operations. For example, to attach a PCI network controller on the + system listed above to the second PCI bus in the guest, as device + 5, function 0, use the following command: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> -\-pciattach 02:00.0@01:05.0</screen> + + <para> + To detach the same device, use: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> -\-pcidetach 02:00.0</screen> + + <para> + Please note that both host and guest could freely assign a + different PCI address to the card attached during runtime, so + those addresses only apply to the address of the card at the + moment of attachment on the host, and during BIOS PCI init on the + guest. + </para> + + <para> + If the virtual machine has a PCI device attached, certain + limitations apply: + </para> + + <itemizedlist> + + <listitem> + <para> + Only PCI cards with non-shared interrupts, such as those using + MSI on the host, are supported at the moment. + </para> + </listitem> + + <listitem> + <para> + No guest state can be reliably saved or restored. The internal + state of the PCI card cannot be retrieved. + </para> + </listitem> + + <listitem> + <para> + Teleportation, also called live migration, does not work. The + internal state of the PCI card cannot be retrieved. + </para> + </listitem> + + <listitem> + <para> + No lazy physical memory allocation. The host will preallocate + the whole RAM required for the VM on startup, as we cannot + catch physical hardware accesses to the physical memory. + </para> + </listitem> + + </itemizedlist> + + </sect1>--> + + <sect1 id="webcam-passthrough"> + + <title>Webcam Passthrough</title> + + <sect2 id="webcam-using-guest"> + + <title>Using a Host Webcam in the Guest</title> + + <para> + &product-name; includes a feature called <emphasis>webcam + passthrough</emphasis>, which enables a guest to use a host + webcam. This complements the general USB passthrough support + which was the typical way of using host webcams in legacy + releases. The webcam passthrough support can handle non-USB + video sources in theory, but this is completely untested. + </para> + + <note> + <para> + The webcam passthrough module is shipped as part of the + &product-name; extension pack, which must be installed + separately. See <xref linkend="intro-installing" />. + </para> + </note> + + <para> + The host webcam can be attached to the VM using the + <emphasis role="bold">Devices</emphasis> menu in the VM menu + bar. The <emphasis role="bold">Webcams</emphasis> menu contains + a list of available video input devices on the host. Clicking on + a webcam name attaches or detaches the corresponding host + device. + </para> + + <para> + The <command>VBoxManage</command> command line tool can be used + to enable webcam passthrough. Please see the host-specific + sections below for additional details. The following commands + are available: + </para> + + <itemizedlist> + + <listitem> + <para> + Get a list of host webcams, or other video input devices: + </para> + +<screen>$ VBoxManage list webcams</screen> + + <para> + The output format is as follows: + </para> + +<screen>alias "user friendly name" +host path or identifier</screen> + + <para> + The alias can be used as a shortcut in other commands. Alias + '.0' means the default video input device on the host. Alias + '.1', '.2'means first, second video input device, and so on. + The device order is host-specific. + </para> + </listitem> + + <listitem> + <para> + Attach a webcam to a running VM, as follows: + </para> + +<screen>VBoxManage controlvm <replaceable>VM name</replaceable> webcam attach [<replaceable>host_path</replaceable>|<replaceable>alias</replaceable> [<replaceable>settings</replaceable>]]</screen> + + <para> + This attaches a USB webcam device to the guest. + </para> + + <para> + The <literal>settings</literal> parameter is a string + <literal>Setting1=Value1;Setting2=Value2</literal>, which + enables you to configure the emulated webcam device. The + following settings are supported: + </para> + + <itemizedlist> + + <listitem> + <para> + <literal>MaxFramerate</literal>: The highest rate at + which video frames are sent to the guest. A higher frame + rate requires more CPU power. Therefore sometimes it is + useful to set a lower limit. Default is no limit and + allow the guest to use all frame rates supported by the + host webcam. + </para> + </listitem> + + <listitem> + <para> + <literal>MaxPayloadTransferSize</literal>: How many + bytes the emulated webcam can send to the guest at a + time. Default value is 3060 bytes, which is used by some + webcams. Higher values can slightly reduce CPU load, if + the guest is able to use larger buffers. However, a high + <literal>MaxPayloadTransferSize</literal> might be not + supported by some guests. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Detach a webcam from a running VM, as follows: + </para> + +<screen>VBoxManage controlvm <replaceable>VM-name</replaceable> webcam detach [<replaceable>host_path</replaceable>|<replaceable>alias</replaceable>]</screen> + </listitem> + + <listitem> + <para> + List the webcams attached to a running VM, as follows: + </para> + +<screen>VBoxManage controlvm <replaceable>VM-name</replaceable> webcam list</screen> + + <para> + The output contains the path or alias which was used in the + <command>webcam attach</command> command for each attached + webcam. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="webcam-win-hosts"> + + <title>Windows Hosts</title> + + <para> + When the webcam device is detached from the host, the emulated + webcam device is automatically detached from the guest. + </para> + + </sect2> + + <sect2 id="webcam-mac-hosts"> + + <title>macOS Hosts</title> + + <para> + When the webcam device is detached from the host, the emulated + webcam device remains attached to the guest and must be manually + detached using the <command>VBoxManage controlvm + <replaceable>VM-name</replaceable> webcam detach</command> + command. + </para> + + </sect2> + + <sect2 id="webcam-linux-hosts"> + + <title>Linux and Oracle Solaris Hosts</title> + + <para> + When the webcam is detached from the host the emulated webcam + device is automatically detached from the guest only if the + webcam is streaming video. If the emulated webcam is inactive it + should be manually detached using the <command>VBoxManage + controlvm <replaceable>VM-name</replaceable> webcam + detach</command> command. + </para> + + <para> + Aliases <filename>.0</filename> and <filename>.1</filename> are + mapped to <filename>/dev/video0</filename>, alias + <filename>.2</filename> is mapped to + <filename>/dev/video1</filename> and so forth. + </para> + + </sect2> + + </sect1> + + <sect1 id="adv-display-config"> + + <title>Advanced Display Configuration</title> + + <sect2 id="customvesa"> + + <title>Custom VESA Resolutions</title> + + <para> + Apart from the standard VESA resolutions, the &product-name; + VESA BIOS enables you to add up to 16 custom video modes which + will be reported to the guest operating system. When using + Windows guests with the &product-name; Guest Additions, a custom + graphics driver will be used instead of the fallback VESA + solution so this information does not apply. + </para> + + <para> + Additional video modes can be configured for each VM using the + extra data facility. The extra data key is called + <literal>CustomVideoMode<replaceable>x</replaceable></literal> + with <replaceable>x</replaceable> being a number from 1 to 16. + Please note that modes will be read from 1 until either the + following number is not defined or 16 is reached. The following + example adds a video mode that corresponds to the native display + resolution of many notebook computers: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "CustomVideoMode1" "1400x1050x16"</screen> + + <para> + The VESA mode IDs for custom video modes start at + <literal>0x160</literal>. In order to use the above defined + custom video mode, the following command line has to be supplied + to Linux: + </para> + +<screen>vga = 0x200 | 0x160 +vga = 864</screen> + + <para> + For guest operating systems with &product-name; Guest Additions, + a custom video mode can be set using the video mode hint + feature. + </para> + + </sect2> + + <sect2 id="max-resolution-guests"> + + <title>Configuring the Maximum Resolution of Guests When Using the Graphical + Frontend</title> + + <para> + When guest systems with the Guest Additions installed are + started using the graphical frontend, the normal &product-name; + application, they will not be allowed to use screen resolutions + greater than the host's screen size unless the user manually + resizes them by dragging the window, switching to full screen or + seamless mode or sending a video mode hint using + <command>VBoxManage</command>. This behavior is what most users + will want, but if you have different needs, you can change it by + issuing one of the following commands from the command line: + </para> + + <itemizedlist> + + <listitem> + <para> + Remove all limits on guest resolutions. + </para> + +<screen>VBoxManage setextradata global GUI/MaxGuestResolution any</screen> + </listitem> + + <listitem> + <para> + Manually specify a maximum resolution. + </para> + +<screen>VBoxManage setextradata global GUI/MaxGuestResolution <replaceable>width</replaceable>x<replaceable>height</replaceable></screen> + </listitem> + + <listitem> + <para> + Restore the default settings to all guest VMs. + </para> + +<screen>VBoxManage setextradata global GUI/MaxGuestResolution auto</screen> + </listitem> + + </itemizedlist> + + </sect2> + + </sect1> + + <sect1 id="adv-storage-config"> + + <title>Advanced Storage Configuration</title> + + <sect2 id="rawdisk"> + + <title>Using a Raw Host Hard Disk From a Guest</title> + + <para> + As an alternative to using virtual disk images as described in + <xref linkend="storage" />, &product-name; can also present + either entire physical hard disks or selected partitions as + virtual disks to virtual machines. + </para> + + <para> + With &product-name;, this type of access is called <emphasis>raw + hard disk access</emphasis>. It enables a guest operating system + to access its virtual hard disk without going through the host + OS file system. The actual performance difference for image + files compared to raw disk varies greatly depending on the + overhead of the host file system, whether dynamically growing + images are used, and on host OS caching strategies. The caching + indirectly also affects other aspects such as failure behavior. + For example, whether the virtual disk contains all data written + before a host OS crash. Consult your host OS documentation for + details on this. + </para> + + <warning> + <para> + Raw hard disk access is for expert users only. Incorrect use + or use of an outdated configuration can lead to + <emphasis role="bold">total loss of data</emphasis> on the + physical disk. Most importantly, <emphasis>do not</emphasis> + attempt to boot the partition with the currently running host + operating system in a guest. This will lead to severe data + corruption. + </para> + </warning> + + <para> + Raw hard disk access, both for entire disks and individual + partitions, is implemented as part of the VMDK image format + support. As a result, you will need to create a special VMDK + image file which defines where the data will be stored. After + creating such a special VMDK image, you can use it like a + regular virtual disk image. For example, you can use the Virtual + Media Manager, see <xref linkend="virtual-media-manager" />, or + <command>VBoxManage</command> to assign the image to a virtual + machine. + </para> + + <sect3 id="rawdisk-access-entire-physical-disk"> + + <title>Access to Entire Physical Hard Disk</title> + + <para> + While this variant is the simplest to set up, you must be + aware that this will give a guest operating system direct and + full access to an <emphasis>entire physical disk</emphasis>. + If your <emphasis>host</emphasis> operating system is also + booted from this disk, please take special care to not access + the partition from the guest at all. On the positive side, the + physical disk can be repartitioned in arbitrary ways without + having to recreate the image file that gives access to the raw + disk. + </para> + + <para> + On a Linux host, to create an image that represents an entire + physical hard disk which will not contain any actual data, as + this will all be stored on the physical disk, use the + following command: + </para> + +<screen>$ VBoxManage createmedium disk --filename <replaceable>path-to-file</replaceable>.vmdk --format=VMDK + --variant RawDisk --property RawDrive=/dev/sda</screen> + + <para> + This creates the + <filename><replaceable>path-to-file</replaceable>.vmdk</filename> + file image that must be an absolute path. All data is read and + written from <filename>/dev/sda</filename>. + </para> + + <para> + On a Windows host, instead of the above device specification, + for example use <filename>\\.\PhysicalDrive0</filename>. On a + macOS host, instead of the above device specification use for + example <filename>/dev/rdisk1</filename>. Note that on Mac OS + X you can only get access to an entire disk if no volume is + mounted from it. + </para> + + <para> + Creating the image requires read/write access for the given + device. Read/write access is also later needed when using the + image from a virtual machine. On some host platforms, such as + Windows, raw disk access may be restricted and not permitted + by the host OS in some situations. + </para> + + <para> + Just like with regular disk images, this does not + automatically attach the newly created image to a virtual + machine. This can be done as follows: + </para> + +<screen>$ VBoxManage storageattach WindowsXP --storagectl "IDE Controller" \ + --port 0 --device 0 --type hdd --medium <replaceable>path-to-file</replaceable>.vmdk</screen> + + <para> + When this is done the selected virtual machine will boot from + the specified physical disk. + </para> + + </sect3> + + <sect3 id="rawdisk-access-disk-partitions"> + + <title>Access to Individual Physical Hard Disk Partitions</title> + + <para> + This <emphasis>raw partition support</emphasis> is quite + similar to the full hard disk access described above. However, + in this case, any partitioning information will be stored + inside the VMDK image. This means that you can install a + different boot loader in the virtual hard disk without + affecting the host's partitioning information. While the guest + will be able to <emphasis>see</emphasis> all partitions that + exist on the physical disk, access will be filtered in that + reading from partitions for which no access is allowed the + partitions will only yield zeroes, and all writes to them are + ignored. + </para> + + <para> + To create a special image for raw partition support, which + will contain a small amount of data, on a Linux host, use the + command: + </para> + +<screen>$ VBoxManage createmedium disk --filename <replaceable>path-to-file</replaceable>.vmdk --format=VMDK +--variant RawDisk --property RawDrive=/dev/sda --property Partitions=1,5</screen> + + <para> + The command is identical to the one for full hard disk access, + except for the additional <option>--property + Partitions=1,5</option> parameter. This example would create + the image + <filename><replaceable>path-to-file</replaceable>.vmdk</filename>, + which must be absolute, and partitions 1 and 5 of + <filename>/dev/sda</filename> would be made accessible to the + guest. + </para> + + <para> + &product-name; uses the same partition numbering as your Linux + host. As a result, the numbers given in the above example + would refer to the first primary partition and the first + logical drive in the extended partition, respectively. + </para> + + <para> + On a Windows host, instead of the above device specification, + use for example <filename>\\.\PhysicalDrive0</filename>. On a + macOS host, instead of the above device specification use + <filename>/dev/rdisk1</filename>, for example. Note that on OS + X you can only use partitions which are not mounted. Unmount + the respective disk first using <emphasis>diskutil unmountDisk + <filename>/dev/diskX</filename></emphasis>. Partition numbers + are the same on Linux, Windows, and macOS hosts. + </para> + + <para> + The numbers for the list of partitions can be taken from the + output of the following command: + </para> + +<screen>$ VBoxManage list hostdrives</screen> + + <para> + The output lists available drives and their partitions with + the partition types and sizes to give the user enough + information to identify the partitions necessary for the + guest. + </para> + + <para> + Images which give access to individual partitions are specific + to a particular host disk setup. You cannot transfer these + images to another host. Also, whenever the host partitioning + changes, the image <emphasis>must be recreated</emphasis>. + </para> + + <para> + Creating the image requires read/write access for the given + device. Read/write access is also later needed when using the + image from a virtual machine. If this is not feasible, there + is a special variant for raw partition access, currently only + available on Linux hosts, that avoids having to give the + current user access to the entire disk. To set up such an + image, use: + </para> + +<screen>$ VBoxManage createmedium disk --filename <replaceable>path-to-file</replaceable>.vmdk --format=VMDK +--variant RawDisk --property RawDrive=/dev/sda --property Partitions=1,5 +--property Relative=1</screen> + + <para> + When used from a virtual machine, the image will then refer + not to the entire disk, but only to the individual partitions. + In this example, <filename>/dev/sda1</filename> and + <filename>/dev/sda5</filename>. As a consequence, read/write + access is only required for the affected partitions, not for + the entire disk. During creation however, read-only access to + the entire disk is required to obtain the partitioning + information. + </para> + + <para> + In some configurations it may be necessary to change the MBR + code of the created image. For example, to replace the Linux + boot loader that is used on the host by another boot loader. + This enables for example the guest to boot directly to + Windows, while the host boots Linux from the "same" disk. For + this purpose the <option>--property-file + BootSector=<replaceable>path-to-file-with-boot-sector</replaceable></option> + parameter is provided. It specifies a file name from which to + take the MBR code. The partition table is not modified at all, + so a MBR file from a system with totally different + partitioning can be used. An example of this is: + </para> + +<screen>$ VBoxManage createmedium disk --filename <replaceable>path-to-file</replaceable>.vmdk --format=VMDK +--variant RawDisk --property RawDrive=/dev/sda --property Partitions=1,5 +--property-file BootSector=winxp.mbr</screen> + + <para> + The modified MBR will be stored inside the image, not on the + host disk. + </para> + + <para> + The created image can be attached to a storage controller in a + VM configuration as usual. + </para> + + </sect3> + + </sect2> + + <sect2 id="changevpd"> + + <title>Configuring the Hard Disk Vendor Product Data (VPD)</title> + + <para> + &product-name; reports vendor product data for its virtual hard + disks which consist of hard disk serial number, firmware + revision and model number. These can be changed using the + following commands: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/ahci/0/Config/Port0/SerialNumber" "serial" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/ahci/0/Config/Port0/FirmwareRevision" "firmware" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/ahci/0/Config/Port0/ModelNumber" "model"</screen> + + <para> + The serial number is a 20 byte alphanumeric string, the firmware + revision an 8 byte alphanumeric string and the model number a 40 + byte alphanumeric string. Instead of Port0, referring to the + first port, specify the desired SATA hard disk port. + </para> + + <para> + The above commands apply to virtual machines with an AHCI (SATA) + controller. The commands for virtual machines with an IDE + controller are: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/SerialNumber" "serial" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/FirmwareRevision" "firmware" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/ModelNumber" "model"</screen> + + <para> + For hard disks, you can mark the drive as having a + non-rotational medium by using the following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/ahci/0/Config/Port0/NonRotational" "1"</screen> + + <para> + Additional three parameters are needed for CD/DVD drives to + report the vendor product data: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIVendorId" "vendor" +VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIProductId" "product" +VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIRevision" "revision"</screen> + + <para> + The vendor id is an 8 byte alphanumeric string, the product id + an 16 byte alphanumeric string and the revision a 4 byte + alphanumeric string. Instead of Port0, referring to the first + port, specify the desired SATA hard disk port. + </para> + + </sect2> + + <sect2 id="iscsi-intnet"> + + <title>Access iSCSI Targets Using Internal Networking</title> + + <para> + As an experimental feature, &product-name; enables access to an + iSCSI target running in a virtual machine which is configured to + use Internal Networking mode. See + <xref linkend="storage-iscsi" />, + <xref linkend="network_internal" />, and + <xref + linkend="vboxmanage-storageattach" />. + </para> + + <para> + The IP stack accessing Internal Networking must be configured in + the virtual machine which accesses the iSCSI target. A free + static IP and a MAC address not used by other virtual machines + must be chosen. In the example below, adapt the name of the + virtual machine, the MAC address, the IP configuration, and the + Internal Networking name (MyIntNet) according to your needs. The + following eight commands must first be issued: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/Devices/IntNetIP/0/Trusted 1 +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/Devices/IntNetIP/0/Config/MAC 08:00:27:01:02:0f +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/Devices/IntNetIP/0/Config/IP 10.0.9.1 +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/Devices/IntNetIP/0/Config/Netmask 255.255.255.0 +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/Devices/IntNetIP/0/LUN#0/Driver IntNet +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/Network MyIntNet +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/TrunkType 2 +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/IsService 1</screen> + + <para> + Finally the iSCSI disk must be attached with the + <option>--intnet</option> option to tell the iSCSI initiator to + use internal networking, as follows: + </para> + +<screen>$ VBoxManage storageattach ... --medium iscsi --server 10.0.9.30 \ +--target iqn.2008-12.com.sun:sampletarget --intnet</screen> + + <para> + Compared to a regular iSCSI setup, the IP address of the target + <emphasis>must</emphasis> be specified as a numeric IP address, + as there is no DNS resolver for internal networking. + </para> + + <para> + The virtual machine with the iSCSI target should be started + before the VM using it is powered on. If a virtual machine using + an iSCSI disk is started without having the iSCSI target powered + up, it can take up to 200 seconds to detect this situation. The + VM will fail to power up. + </para> + + </sect2> + + </sect1> + + <sect1 id="changenat"> + + <title>Fine Tuning the &product-name; NAT Engine</title> + + <sect2 id="nat-address-config"> + + <title>Configuring the Address of a NAT Network Interface</title> + + <para> + In NAT mode, the guest network interface is assigned to the IPv4 + range <literal>10.0.<replaceable>x</replaceable>.0/24</literal> + by default where <replaceable>x</replaceable> corresponds to the + instance of the NAT interface +2. So + <replaceable>x</replaceable> is 2 when there is only one NAT + instance active. In that case the guest is assigned to the + address <literal>10.0.2.15</literal>, the gateway is set to + <literal>10.0.2.2</literal> and the name server can be found at + <literal>10.0.2.3</literal>. + </para> + + <para> + If the NAT network needs to be changed, use the following + command: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> \ +--natnet1 "192.168/16"</screen> + + <para> + This command would reserve the network addresses from + <literal>192.168.0.0</literal> to + <literal>192.168.254.254</literal> for the first NAT network + instance of <replaceable>VM-name</replaceable> The guest IP + would be assigned to <literal>192.168.0.15</literal> and the + default gateway could be found at + <literal>192.168.0.2</literal>. + </para> + + </sect2> + + <sect2 id="nat-adv-tftp"> + + <title>Configuring the Boot Server (Next Server) of a NAT Network Interface</title> + + <para> + For network booting in NAT mode, by default &product-name; uses + a built-in TFTP server at the IP address 10.0.2.4. This default + behavior should work fine for typical remote-booting scenarios. + However, it is possible to change the boot server IP and the + location of the boot image with the following commands: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> \ +--nattftpserver1 10.0.2.2 +$ VBoxManage modifyvm <replaceable>VM-name</replaceable> \ +--nattftpfile1 /srv/tftp/boot/MyPXEBoot.pxe</screen> + + </sect2> + + <sect2 id="nat-adv-settings"> + + <title>Tuning TCP/IP Buffers for NAT</title> + + <para> + The &product-name; NAT stack performance is often determined by + its interaction with the host's TCP/IP stack and the size of + several buffers, <literal>SO_RCVBUF</literal> and + <literal>SO_SNDBUF</literal>. For certain setups users might + want to adjust the buffer size for a better performance. This + can by achieved using the following commands, where values are + in kilobytes and can range from 8 to 1024: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> \ +--natsettings1 16000,128,128,0,0</screen> + + <para> + This example illustrates tuning the NAT settings. The first + parameter is the MTU, then the size of the socket's send buffer + and the size of the socket's receive buffer, the initial size of + the TCP send window, and lastly the initial size of the TCP + receive window. Note that specifying zero means fallback to the + default value. + </para> + + <para> + Each of these buffers has a default size of 64KB and default MTU + is 1500. + </para> + + </sect2> + + <sect2 id="nat-bind-sockets"> + + <title>Binding NAT Sockets to a Specific Interface</title> + + <para> + By default, &product-name;'s NAT engine will route TCP/IP + packets through the default interface assigned by the host's + TCP/IP stack. The technical reason for this is that the NAT + engine uses sockets for communication. If you want to change + this behavior, you can tell the NAT engine to bind to a + particular IP address instead. For example, use the following + command: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> \ +--natbindip1 "10.45.0.2"</screen> + + <para> + After this, all outgoing traffic will be sent through the + interface with the IP address 10.45.0.2. Ensure that this + interface is up and running before changing the NAT bind + address. + </para> + + </sect2> + + <sect2 id="nat-adv-dns"> + + <title>Enabling DNS Proxy in NAT Mode</title> + + <para> + The NAT engine by default offers the same DNS servers to the + guest that are configured on the host. In some scenarios, it can + be desirable to hide the DNS server IPs from the guest, for + example when this information can change on the host due to + expiring DHCP leases. In this case, you can tell the NAT engine + to act as DNS proxy using the following command: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --natdnsproxy1 on</screen> + + </sect2> + + <sect2 id="nat_host_resolver_proxy"> + + <title>Using the Host's Resolver as a DNS Proxy in NAT Mode</title> + + <para> + For resolving network names, the DHCP server of the NAT engine + offers a list of registered DNS servers of the host. If for some + reason you need to hide this DNS server list and use the host's + resolver settings, thereby forcing the &product-name; NAT engine + to intercept DNS requests and forward them to host's resolver, + use the following command: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --natdnshostresolver1 on</screen> + + <para> + Note that this setting is similar to the DNS proxy mode, however + whereas the proxy mode just forwards DNS requests to the + appropriate servers, the resolver mode will interpret the DNS + requests and use the host's DNS API to query the information and + return it to the guest. + </para> + + <sect3 id="nat_host_resolver_name_intercepting"> + + <title>User-Defined Host Name Resolving</title> + + <para> + In some cases it might be useful to intercept the name + resolving mechanism, providing a user-defined IP address on a + particular DNS request. The intercepting mechanism enables the + user to map not only a single host but domains and even more + complex naming conventions if required. + </para> + + <para> + The following command sets a rule for mapping a name to a + specified IP: + </para> + +<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \ +<replaceable>unique-rule-name-of-interception-rule</replaceable>/HostIP" <replaceable>IPv4</replaceable> + +VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \ +<replaceable>unique-rule-name</replaceable>/HostName" <replaceable>hostname</replaceable></screen> + + <para> + The following command sets a rule for mapping a pattern name + to a specified IP: + </para> + +<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \ +<replaceable>unique-rule-name</replaceable>/HostIP" <replaceable>IPv4</replaceable> + +VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \ +<replaceable>unique-rule-name</replaceable>/HostNamePattern" <replaceable>hostpattern</replaceable></screen> + + <para> + The host name pattern can include the following wildcard + characters: pipe (<literal>|</literal>), question mark + (<literal>?</literal>), and asterisk (<literal>*</literal>). + </para> + + <para> + This example demonstrates how to instruct the host-resolver + mechanism to resolve all domain and probably some mirrors of + www.blocked-site.info site with IP 127.0.0.1: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/e1000/0/LUN#0/AttachedDriver/Config/HostResolverMappings/all_blocked_site/HostIP" 127.0.0.1 +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/e1000/0/LUN#0/AttachedDriver/Config/HostResolverMappings/all_blocked_site/HostNamePattern" "*.blocked-site.*|*.fb.org"</screen> + + <para> + The host resolver mechanism should be enabled to use + user-defined mapping rules, otherwise they do not have any + effect. + </para> + + </sect3> + + </sect2> + + <sect2 id="nat-adv-alias"> + + <title>Configuring Aliasing of the NAT Engine</title> + + <para> + By default, the NAT core uses aliasing and uses random ports + when generating an alias for a connection. This works well for + the most protocols like SSH, FTP and so on. Though some + protocols might need a more transparent behavior or may depend + on the real port number the packet was sent from. You can change + the NAT mode by using the following commands: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> \ +--nataliasmode1 proxyonly</screen> + +<screen>$ VBoxManage modifyvm "Linux Guest" --nataliasmode1 sameports</screen> + + <para> + The first example disables aliasing and switches NAT into + transparent mode, the second example enforces preserving of port + values. These modes can be combined if necessary. + </para> + + </sect2> + + </sect1> + + <sect1 id="changedmi"> + + <title>Configuring the BIOS DMI Information</title> + + <para> + The DMI data that &product-name; provides to guests can be changed + for a specific VM. Use the following commands to configure the DMI + BIOS information. In case your VM is configured to use EFI + firmware you need to replace <literal>pcbios</literal> by + <literal>efi</literal> in the keys. + </para> + + <itemizedlist> + + <listitem> + <para> + DMI BIOS information (type 0) + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVendor" "BIOS Vendor" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVersion" "BIOS Version" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseDate" "BIOS Release Date" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMajor" 1 +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMinor" 2 +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMajor" 3 +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMinor" 4</screen> + </listitem> + + <listitem> + <para> + DMI system information (type 1) + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemVendor" "System Vendor" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemProduct" "System Product" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemVersion" "System Version" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial" "System Serial" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemSKU" "System SKU" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemFamily" "System Family" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemUuid" \ +"9852bf98-b83c-49db-a8de-182c42c7226b"</screen> + </listitem> + + <listitem> + <para> + DMI board information (type 2) + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardVendor" "Board Vendor" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardProduct" "Board Product" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardVersion" "Board Version" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardSerial" "Board Serial" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardAssetTag" "Board Tag" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardLocInChass" "Board Location" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardBoardType" 10</screen> + </listitem> + + <listitem> + <para> + DMI system enclosure or chassis (type 3) + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiChassisVendor" "Chassis Vendor" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiChassisType" 3 +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiChassisVersion" "Chassis Version" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiChassisSerial" "Chassis Serial" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiChassisAssetTag" "Chassis Tag"</screen> + </listitem> + + <listitem> + <para> + DMI processor information (type 4) + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiProcManufacturer" "GenuineIntel" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiProcVersion" "Pentium(R) III"</screen> + </listitem> + + <listitem> + <para> + DMI OEM strings (type 11) + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxVer" "vboxVer_1.2.3" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxRev" "vboxRev_12345"</screen> + </listitem> + + </itemizedlist> + + <para> + If a DMI string is not set, the default value of &product-name; is + used. To set an empty string use + <literal>"<EMPTY>"</literal>. + </para> + + <para> + Note that in the above list, all quoted parameters (DmiBIOSVendor, + DmiBIOSVersion but not DmiBIOSReleaseMajor) are expected to be + strings. If such a string is a valid number, the parameter is + treated as number and the VM will most probably refuse to start + with an <literal>VERR_CFGM_NOT_STRING</literal> error. In that + case, use + <literal>"string:<replaceable>value</replaceable>"</literal>. For + example: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial" "string:1234"</screen> + + <para> + Changing this information can be necessary to provide the DMI + information of the host to the guest to prevent Windows from + asking for a new product key. On Linux hosts, the DMI BIOS + information can be obtained with the following command: + </para> + +<screen>$ dmidecode -t0</screen> + + <para> + The DMI system information can be obtained as follows: + </para> + +<screen>$ dmidecode -t1</screen> + + </sect1> + + <sect1 id="changeacpicust"> + + <title>Configuring Custom ACPI Tables</title> + + <para> + You can configure &product-name; to present up to four custom ACPI + tables to the guest. Use a command such as the following to + configure custom ACPI tables. Note that + <literal>CustomTable1</literal>, <literal>CustomTable2</literal>, + and <literal>CustomTable3</literal> are available in addition to + <literal>CustomTable0</literal>. + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/acpi/0/Config/CustomTable0" "/<replaceable>path-to-table</replaceable>.bin"</screen> + + <para> + Configuring custom ACPI tables can for example avoid the need for + asking for a new product key on Windows Vista, Windows 7, Windows + 8 and later guests. On Linux hosts, one of the system's ACPI + tables can be read from + <filename>/sys/firmware/acpi/tables/</filename>. + </para> + + </sect1> + + <sect1 id="fine-tune-timers"> + + <title>Fine Tuning Timers and Time Synchronization</title> + + <sect2 id="changetscmode"> + + <title>Configuring the Guest Time Stamp Counter (TSC) to Reflect Guest + Execution</title> + + <para> + By default, &product-name; keeps all sources of time visible to + the guest synchronized to a single time source, the monotonic + host time. This reflects the assumptions of many guest operating + systems, which expect all time sources to reflect "wall clock" + time. In special circumstances it may be useful however to make + the time stamp counter (TSC) in the guest reflect the time + actually spent executing the guest. + </para> + + <para> + This special TSC handling mode can be enabled on a per-VM basis, + and for best results must be used only in combination with + hardware virtualization. To enable this mode use the following + command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal/TM/TSCTiedToExecution" 1</screen> + + <para> + To revert to the default TSC handling mode use: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal/TM/TSCTiedToExecution"</screen> + + <para> + Note that if you use the special TSC handling mode with a guest + operating system which is very strict about the consistency of + time sources you may get a warning or error message about the + timing inconsistency. It may also cause clocks to become + unreliable with some guest operating systems depending on how + they use the TSC. + </para> + + </sect2> + + <sect2 id="warpguest"> + + <title>Accelerate or Slow Down the Guest Clock</title> + + <para> + For certain purposes it can be useful to accelerate or to slow + down the virtual guest clock. This can be achieved as follows: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal/TM/WarpDrivePercentage" 200</screen> + + <para> + The above example will double the speed of the guest clock while + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal/TM/WarpDrivePercentage" 50</screen> + + <para> + will halve the speed of the guest clock. Note that changing the + rate of the virtual clock can confuse the guest and can even + lead to abnormal guest behavior. For instance, a higher clock + rate means shorter timeouts for virtual devices with the result + that a slightly increased response time of a virtual device due + to an increased host load can cause guest failures. Note further + that any time synchronization mechanism will frequently try to + resynchronize the guest clock with the reference clock, which is + the host clock if the &product-name; Guest Additions are active. + Therefore any time synchronization should be disabled if the + rate of the guest clock is changed as described above. See + <xref linkend="changetimesync" />. + </para> + + </sect2> + + <sect2 id="changetimesync"> + + <title>Tuning the Guest Additions Time Synchronization Parameters</title> + + <para> + The &product-name; Guest Additions ensure that the guest's + system time is synchronized with the host time. There are + several parameters which can be tuned. The parameters can be set + for a specific VM using the following command: + </para> + +<screen>$ VBoxManage guestproperty set <replaceable>VM-name</replaceable> "/VirtualBox/GuestAdd/VBoxService/<replaceable>property</replaceable>" <replaceable>value</replaceable></screen> + + <para> + <replaceable>property</replaceable> is one of the following: + </para> + + <variablelist> + + <varlistentry> + <term> + <option>--timesync-interval</option> + </term> + + <listitem> + <para> + Specifies the interval at which to synchronize the time + with the host. The default is 10000 ms (10 seconds). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>--timesync-min-adjust</option> + </term> + + <listitem> + <para> + The minimum absolute drift value measured in milliseconds + to make adjustments for. The default is 1000 ms on OS/2 + and 100 ms elsewhere. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>--timesync-latency-factor</option> + </term> + + <listitem> + <para> + The factor to multiply the time query latency with to + calculate the dynamic minimum adjust time. The default is + 8 times, which means as follows: + </para> + + <para> + Measure the time it takes to determine the host time, the + guest has to contact the VM host service which may take + some time. Multiply this value by 8 and do an adjustment + only if the time difference between host and guest is + bigger than this value. Do not do any time adjustment + otherwise. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>--timesync-max-latency</option> + </term> + + <listitem> + <para> + The max host timer query latency to accept. The default is + 250 ms. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>--timesync-set-threshold</option> + </term> + + <listitem> + <para> + The absolute drift threshold, given as milliseconds where + to start setting the time instead of trying to smoothly + adjust it. The default is 20 minutes. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>--timesync-set-start</option> + </term> + + <listitem> + <para> + Set the time when starting the time sync service. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>--timesync-set-on-restore 0|1</option> + </term> + + <listitem> + <para> + Set the time after the VM was restored from a saved state + when passing 1 as parameter. This is the default. Disable + by passing 0. In the latter case, the time will be + adjusted smoothly, which can take a long time. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + All these parameters can be specified as command line parameters + to VBoxService as well. + </para> + + </sect2> + + <sect2 id="disabletimesync"> + + <title>Disabling the Guest Additions Time Synchronization</title> + + <para> + Once installed and started, the &product-name; Guest Additions + will try to synchronize the guest time with the host time. This + can be prevented by forbidding the guest service from reading + the host clock: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal/Devices/VMMDev/0/Config/GetHostTimeDisabled" 1</screen> + + </sect2> + + </sect1> + + <sect1 id="vboxbowsolaris11"> + + <title>Installing the Alternate Bridged Networking Driver on Oracle Solaris 11 + Hosts</title> + + <para> + &product-name; includes a network filter driver that utilizes + Oracle Solaris 11's Crossbow functionality. By default, this new + driver is installed for Oracle Solaris 11 hosts that have support + for it. + </para> + + <para> + To force installation of the older STREAMS based network filter + driver, execute as root the following command before installing + the &product-name; package: + </para> + +<screen>$ touch /etc/vboxinst_vboxflt</screen> + + <para> + To force installation of the Crossbow based network filter driver, + execute as root the following command before installing the + &product-name; package: + </para> + +<screen>$ touch /etc/vboxinst_vboxbow</screen> + + <para> + To check which driver is currently being used by &product-name;, + execute: + </para> + +<screen>$ modinfo | grep vbox</screen> + + <para> + If the output contains "vboxbow", it indicates &product-name; is + using the Crossbow network filter driver, while the name "vboxflt" + indicates usage of the older STREAMS network filter. + </para> + + </sect1> + + <sect1 id="vboxbowvnictemplates"> + + <title>&product-name; VNIC Templates for VLANs on Oracle Solaris 11 Hosts</title> + + <para> + &product-name; supports Virtual Network Interface (VNIC) templates + for configuring VMs over VLANs. An &product-name; VNIC template is + a VNIC whose name starts with + <filename>vboxvnic_template</filename>. The string is + case-sensitive. + </para> + + <para> + On Oracle Solaris 11 hosts, when Crossbow-based bridged networking + is used, a VNIC template may be used to specify the VLAN ID to use + while bridging over a network link. + </para> + + <para> + The following is an example of how to use a VNIC template to + configure a VM over a VLAN. Create an &product-name; VNIC + template, by executing as root: + </para> + +<screen># dladm create-vnic -t -l nge0 -v 23 vboxvnic_template0</screen> + + <para> + This will create a temporary VNIC template over interface + <command>nge0</command> with the VLAN ID 23. To create VNIC + templates that are persistent across host reboots, skip the + <option>-t</option> parameter in the above command. You may check + the current state of links using the following command: + </para> + +<screen>$ dladm show-link +LINK CLASS MTU STATE BRIDGE OVER +nge0 phys 1500 up -- -- +nge1 phys 1500 down -- -- +vboxvnic_template0 vnic 1500 up -- nge0 + +$ dladm show-vnic +LINK OVER SPEED MACADDRESS MACADDRTYPE VID +vboxvnic_template0 nge0 1000 2:8:20:25:12:75 random 23</screen> + + <para> + Once the VNIC template is created, any VMs that need to be on VLAN + 23 over the interface <command>nge0</command> can be configured to + bridge using this VNIC template. + </para> + + <para> + VNIC templates makes managing VMs on VLANs simpler and efficient. + The VLAN details are not stored as part of every VM's + configuration but rather inherited from the VNIC template while + starting the VM. The VNIC template itself can be modified anytime + using the <command>dladm</command> command. + </para> + + <para> + VNIC templates can be created with additional properties such as + bandwidth limits and CPU fanout. Refer to your Oracle Solaris + network documentation for details. The additional properties are + also applied to VMs which bridge using the VNIC template. + </para> + + </sect1> + + <sect1 id="addhostonlysolaris"> + + <title>Configuring Multiple Host-Only Network Interfaces on Oracle Solaris + Hosts</title> + + <para> + By default &product-name; provides you with one host-only network + interface. Adding more host-only network interfaces on Oracle + Solaris hosts requires manual configuration. Here is how to add + another host-only network interface. + </para> + + <para> + Begin by stopping all running VMs. Then, unplumb the existing + "vboxnet0" interface by execute the following command as root: + </para> + +<screen># ifconfig vboxnet0 unplumb</screen> + + <para> + If you have several vboxnet interfaces, you will need to unplumb + all of them. Once all vboxnet interfaces are unplumbed, remove the + driver by executing the following command as root: + </para> + +<screen># rem_drv vboxnet</screen> + + <para> + Edit the file + <filename>/platform/i86pc/kernel/drv/vboxnet.conf</filename> and + add a line for the new interface we want to add as shown below: + </para> + +<screen>name="vboxnet" parent="pseudo" instance=1; +name="vboxnet" parent="pseudo" instance=2;</screen> + + <para> + Add as many of these lines as required with each line having a + unique instance number. + </para> + + <para> + Next, reload the vboxnet driver by executing the following command + as root: + </para> + +<screen># add_drv vboxnet</screen> + + <para> + On Oracle Solaris 11.1 and newer hosts you may want to rename the + default vanity interface name. To check what name has been + assigned, execute: + </para> + +<screen>$ dladm show-phys +LINK MEDIA STATE SPEED DUPLEX DEVICE +net0 Ethernet up 100 full e1000g0 +net2 Ethernet up 1000 full vboxnet1 +net1 Ethernet up 1000 full vboxnet0</screen> + + <para> + In the above example, we can rename "net2" to "vboxnet1" before + proceeding to plumb the interface. This can be done by executing + as root: + </para> + +<screen># dladm rename-link net2 vboxnet1</screen> + + <para> + Now plumb all the interfaces using <command>ifconfig + vboxnet<replaceable>X</replaceable> plumb</command>, where + <replaceable>X</replaceable> would be 1 in this case. Once the + interface is plumbed, it may be configured like any other network + interface. Refer to the <command>ifconfig</command> documentation + for further details. + </para> + + <para> + To make the settings for the newly added interfaces persistent + across reboots, you will need to edit the files + <filename>/etc/inet/netmasks</filename>, and if you are using NWAM + <filename>/etc/nwam/llp</filename> and add the appropriate entries + to set the netmask and static IP for each of those interfaces. The + &product-name; installer only updates these configuration files + for the one "vboxnet0" interface it creates by default. + </para> + + </sect1> + + <sect1 id="solariscodedumper"> + + <title>Configuring the &product-name; CoreDumper on Oracle Solaris Hosts</title> + + <para> + &product-name; is capable of producing its own core files for + extensive debugging when things go wrong. Currently this is only + available on Oracle Solaris hosts. + </para> + + <para> + The &product-name; CoreDumper can be enabled using the following + command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> VBoxInternal2/CoreDumpEnabled 1</screen> + + <para> + You can specify which directory to use for core dumps with this + command, as follows: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> VBoxInternal2/CoreDumpDir <replaceable>path-to-directory</replaceable></screen> + + <para> + Make sure the directory you specify is on a volume with sufficient + free space and that the &product-name; process has sufficient + permissions to write files to this directory. If you skip this + command and do not specify any core dump directory, the current + directory of the &product-name; executable will be used. This + would most likely fail when writing cores as they are protected + with root permissions. It is recommended you explicitly set a core + dump directory. + </para> + + <para> + You must specify when the &product-name; CoreDumper should be + triggered. This is done using the following commands: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> VBoxInternal2/CoreDumpReplaceSystemDump 1 +$ VBoxManage setextradata <replaceable>VM-name</replaceable> VBoxInternal2/CoreDumpLive 1</screen> + + <para> + At least one of the above two commands will have to be provided if + you have enabled the &product-name; CoreDumper. + </para> + + <para> + Setting <literal>CoreDumpReplaceSystemDump</literal> sets up the + VM to override the host's core dumping mechanism and in the event + of any crash only the &product-name; CoreDumper would produce the + core file. + </para> + + <para> + Setting <literal>CoreDumpLive</literal> sets up the VM to produce + cores whenever the VM process receives a + <literal>SIGUSR2</literal> signal. After producing the core file, + the VM will not be terminated and will continue to run. You can + thus take cores of the VM process using the following command: + </para> + +<screen>$ kill -s SIGUSR2 <replaceable>VM-process-id</replaceable></screen> + + <para> + The &product-name; CoreDumper creates core files of the form + <filename>core.vb.<replaceable>process-name</replaceable>.<replaceable>process-ID</replaceable></filename> + such as <filename>core.vb.VBoxHeadless.11321</filename>. + </para> + + </sect1> + + <sect1 id="vboxandsolzvmm"> + + <title>&product-name; and Oracle Solaris Kernel Zones</title> + + <para> + Oracle Solaris kernel zones on x86-based systems make use of + hardware-assisted virtualization features like &product-name; + does. However, for kernel zones and &product-name; to share this + hardware resource, they need to cooperate. + </para> + + <para> + By default, due to performance reasons, &product-name; acquires + the hardware-assisted virtualization resource (VT-x/AMD-V) + globally on the host machine and uses it until the last + &product-name; VM that requires it is powered off. This prevents + other software from using VT-x/AMD-V during the time + &product-name; has taken control of it. + </para> + + <para> + &product-name; can be instructed to relinquish use of + hardware-assisted virtualization features when not executing guest + code, thereby allowing kernel zones to make use of them. To do + this, shutdown all &product-name; VMs and execute the following + command: + </para> + +<screen>$ VBoxManage setproperty hwvirtexclusive off</screen> + + <para> + This command needs to be executed only once as the setting is + stored as part of the global &product-name; settings which will + continue to persist across host-reboots and &product-name; + upgrades. + </para> + + </sect1> + + <sect1 id="guitweaks"> + + <title>Locking Down &vbox-mgr;</title> + + <sect2 id="customize-vm-manager"> + + <title>Customizing &vbox-mgr;</title> + + <para> + There are several advanced customization settings for locking + down &vbox-mgr;. Locking down means removing some features that + the user should not see. + </para> + +<screen>VBoxManage setextradata global GUI/Customizations <replaceable>property</replaceable>[,<replaceable>property</replaceable> ...]</screen> + + <para> + <replaceable>property</replaceable> is one of the following + properties: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>noSelector</literal> + </term> + + <listitem> + <para> + Do not allow users to start &vbox-mgr;. Trying to do so + will show a window containing a proper error message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>noMenuBar</literal> + </term> + + <listitem> + <para> + VM windows will not contain a menu bar. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>noStatusBar</literal> + </term> + + <listitem> + <para> + VM windows will not contain a status bar. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + To disable any of these &vbox-mgr; customizations use the + following command: + </para> + +<screen>$ VBoxManage setextradata global GUI/Customizations</screen> + + </sect2> + + <sect2 id="customize-vm-selector"> + + <title>VM Selector Customization</title> + + <para> + The following per-machine VM extradata settings can be used to + change the behavior of the VM selector window in respect of + certain VMs: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> <replaceable>property</replaceable> true</screen> + + <para> + <replaceable>property</replaceable> can be any of the following: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>GUI/HideDetails</literal> + </term> + + <listitem> + <para> + Do not show the VM configuration of a certain VM. The + details window will remain just empty if this VM is + selected. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>GUI/PreventReconfiguration</literal> + </term> + + <listitem> + <para> + Do not allow the user to open the + <emphasis role="bold">Settings</emphasis> dialog for a + certain VM. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>GUI/PreventSnapshotOperations</literal> + </term> + + <listitem> + <para> + Prevent snapshot operations for a VM from the GUI, either + at runtime or when the VM is powered off. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>GUI/HideFromManager</literal> + </term> + + <listitem> + <para> + Hide a certain VM in the VM selector window. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>GUI/PreventApplicationUpdate</literal> + </term> + + <listitem> + <para> + Disable the automatic update check and hide the + corresponding menu item. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + Note that these settings do not prevent the user from + reconfiguring the VM by using the <command>VBoxManage + modifyvm</command> command. + </para> + + </sect2> + + <sect2 id="config-vm-selector-menu"> + + <title>Configure VM Selector Menu Entries</title> + + <para> + You can disable certain entries in the global settings page of + the VM selector: + </para> + +<screen>$ VBoxManage setextradata global GUI/RestrictedGlobalSettingsPages <replaceable>property</replaceable>[,<replaceable>property</replaceable>...]</screen> + + <para> + <replaceable>property</replaceable> is one of the following: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>General</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">General</emphasis> + settings pane. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Input</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Input</emphasis> + settings pane. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Update</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Update</emphasis> + settings pane. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Language</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Language</emphasis> + settings pane. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Display</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Display</emphasis> + settings pane. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Network</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Network</emphasis> + settings pane. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Extensions</literal> + </term> + + <listitem> + <para> + Do not show the + <emphasis role="bold">Extensions</emphasis> settings pane. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Proxy</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Proxy</emphasis> + settings pane. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a global setting. You can specify any combination of + properties. To restore the default behavior, use the following + command: + </para> + +<screen>$ VBoxManage setextradata global GUI/RestrictedGlobalSettingsPages</screen> + + </sect2> + + <sect2 id="config-vm-window-menu"> + + <title>Configure VM Window Menu Entries</title> + + <para> + You can disable certain menu actions in the VM window: + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMenus OPTION[,OPTION...]</screen> + + <para> + where <literal>OPTION</literal> is one of the following + keywords: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>All</literal> + </term> + + <listitem> + <para> + Do not show any menu in the VM window. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Application</literal> + </term> + + <listitem> + <para> + Do not show + <emphasis role="bold">Application/File</emphasis> menu in + the VM window. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Machine</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Machine</emphasis> + menu in the VM window. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>View</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">View</emphasis> menu + in the VM window. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Input</literal> + </term> + + <listitem> + <para> + Do not show <emphasis role="bold">Input</emphasis> menu in + the VM window. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Devices</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Devices</emphasis> + menu in the VM window. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Help</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Help</emphasis> menu + in the VM window. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Debug</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Debug</emphasis> + menu in the VM window. The Debug menu is only visible if + the GUI was started with special command line parameters + or environment variable settings. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use the following + command: + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMenus</screen> + + <para> + You can also disable certain menu actions of certain menus. Use + the following command to disable certain actions of the + <emphasis role="bold">Application</emphasis> menu. This is only + available on macOS hosts. + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeApplicationMenuActions OPTION[,OPTION...]</screen> + + <para> + where <literal>OPTION</literal> is one of the following + keywords: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>All</literal> + </term> + + <listitem> + <para> + Do not show any menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>About</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">About</emphasis> + menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Preferences</literal> + </term> + + <listitem> + <para> + Do not show the + <emphasis role="bold">Preferences</emphasis> menu item in + this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>NetworkAccessManager</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Network Operations + Manager</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>ResetWarnings</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Reset All + Warnings</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Close</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Close</emphasis> + menu item in this menu. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use the following + command: + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMenus</screen> + + <para> + Use the following command to disable certain actions of the + <emphasis role="bold">Machine</emphasis> menu: + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMachineMenuActions OPTION[,OPTION...]</screen> + + <para> + where <literal>OPTION</literal> is one of the following + keywords: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>All</literal> + </term> + + <listitem> + <para> + Do not show any menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>SettingsDialog</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Settings</emphasis> + menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>TakeSnapshot</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Take + Snapshot...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>InformationDialog</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Session + Information...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>FileManagerDialog</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">File + Manager...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Pause</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Pause</emphasis> + menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Reset</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Reset</emphasis> + menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Shutdown</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">ACPI + Shutdown</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMachineMenuActions</screen> + + <para> + Use the following command to disable certain actions of the + <emphasis role="bold">View</emphasis> menu: + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeViewMenuActions OPTION[,OPTION...]</screen> + + <para> + where <literal>OPTION</literal> is one of the following + keywords: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>All</literal> + </term> + + <listitem> + <para> + Do not show any menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Fullscreen</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Full-screen + Mode</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Seamless</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Seamless + Mode</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Scale</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Scaled + Mode</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>GuestAutoresize</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Auto-resize Guest + Display</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>AdjustWindow</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Adjust Window + Size</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>TakeScreenshot</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Take + Screenshot...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Recording</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Recording</emphasis> + menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>VRDEServer</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Remote + Display</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>MenuBar</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Menu Bar</emphasis> + menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>MenuBarSettings</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Menu Bar + Settings...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>StatusBar</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Status + Bar</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>StatusbarSettings</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Statusbar + Settings...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeViewMenuActions</screen> + + <para> + Use the following command to disable certain actions of the + <emphasis role="bold">Input</emphasis> menu: + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeInputMenuActions OPTION[,OPTION...]</screen> + + <para> + where <literal>OPTION</literal> is one of the following + keywords: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>All</literal> + </term> + + <listitem> + <para> + Do not show any menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Keyboard</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Keyboard</emphasis> + menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>KeyboardSettings</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Keyboard + Settings...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>SoftKeyboard</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Soft + Keyboard...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>TypeCAD</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Insert + Ctrl-Alt-Del</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>TypeCABS</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Insert + Ctrl-Alt-Backspace</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>TypeCtrlBreak</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Insert + Ctrl-Break</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>TypeInsert</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Insert + Insert</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>TypePrintScreen</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Insert Print + Screen</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>TypeAltPrintScreen</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Insert Alt Print + Screen</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>TypeHostKeyCombo</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Insert Host Key + Combo</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>MouseIntegration</literal> + </term> + + <listitem> + <para> + Do not show the + <emphasis role="bold">MouseIntegration</emphasis> menu + item in this menu. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeInputMenuActions</screen> + + <para> + Use the following command to disable certain actions of the + <emphasis role="bold">Devices</emphasis> menu: + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeDevicesMenuActions OPTION[,OPTION...]</screen> + + <para> + where <literal>OPTION</literal> is one of the following keywords + to disable actions in the + <emphasis role="bold">Devices</emphasis> menu: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>All</literal> + </term> + + <listitem> + <para> + Do not show any menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>HardDrives</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Hard + Disks</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>OpticalDevices</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Optical + Devices</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>FloppyDevices</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Floppy + Drives</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Audio</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Audio</emphasis> + menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Network</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Network</emphasis> + menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>NetworkSettings</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Network + Settings</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>USBDevices</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">USB </emphasis> menu + item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>WebCams</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">WebCams </emphasis> + menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>SharedFolders</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Shared + Folders</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>SharedFoldersSettings</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Shared Folders + Settings...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>SharedClipboard</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Shared + Clipboard</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>DragAndDrop</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Drag and + Drop</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>InstallGuestTools</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Insert Guest + Additions CD image...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM or global or global setting. Any combination of + the above is allowed. To restore the default behavior, use + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeDevicesMenuActions</screen> + + <para> + Use the following command to disable certain actions of the + <emphasis role="bold">Debug</emphasis> menu: + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeDebuggerMenuActions OPTION[,OPTION...]</screen> + + <para> + where <literal>OPTION</literal> is one of the following keywords + to disable actions in the <emphasis>Debug</emphasis> menu, which + is normally completely disabled: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>All</literal> + </term> + + <listitem> + <para> + Do not show any menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Statistics</literal> + </term> + + <listitem> + <para> + Do not show the + <emphasis role="bold">Statistics...</emphasis> menu item + in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>CommandLine</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Command + Line...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Logging</literal> + </term> + + <listitem> + <para> + Do not show the + <emphasis role="bold">Logging...</emphasis> menu item in + this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>LogDialog</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Show + Log...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>GuestControlConsole</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Guest Control + Terminal...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeDebuggerMenuActions</screen> + + <para> + Use the following command to disable certain actions of the + <emphasis role="bold">View</emphasis> menu: + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeHelpMenuActions OPTION[,OPTION...]</screen> + + <para> + where <literal>OPTION</literal> is one of the following keywords + to disable actions in the <emphasis role="bold">Help</emphasis> + menu, which is normally completely disabled: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>All</literal> + </term> + + <listitem> + <para> + Do not show any menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Contents</literal> + </term> + + <listitem> + <para> + Do not show the + <emphasis role="bold">Contents...</emphasis> menu item in + this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>WebSite</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">VirtualBox Web + Site...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>BugTracker</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">VirtualBox Bug + Tracker...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Forums</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">VirtualBox + Forums...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Oracle</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Oracle Web + Site...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>About</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">About + VirtualBox...</emphasis> menu item in this menu. Only for + non-macOS hosts. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeHelpMenuActions</screen> + + </sect2> + + <sect2 id="config-vm-window-status-bar"> + + <title>Configure VM Window Status Bar Entries</title> + + <para> + You can disable certain status bar items: + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedStatusBarIndicators OPTION[,OPTION...]</screen> + + <para> + where <literal>OPTION</literal> is one of the following + keywords: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>HardDisks</literal> + </term> + + <listitem> + <para> + Do not show the hard disk icon in the VM window status + bar. By default the hard disk icon is only shown if the VM + configuration contains one or more hard disks. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>OpticalDisks</literal> + </term> + + <listitem> + <para> + Do not show the CD icon in the VM window status bar. By + default the CD icon is only shown if the VM configuration + contains one or more CD drives. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>FloppyDisks</literal> + </term> + + <listitem> + <para> + Do not show the floppy icon in the VM window status bar. + By default the floppy icon is only shown if the VM + configuration contains one or more floppy drives. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Network</literal> + </term> + + <listitem> + <para> + Do not show the network icon in the VM window status bar. + By default the network icon is only shown if the VM + configuration contains one or more active network + adapters. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>USB</literal> + </term> + + <listitem> + <para> + Do not show the USB icon in the status bar. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>SharedFolders</literal> + </term> + + <listitem> + <para> + Do not show the shared folders icon in the status bar. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Capture</literal> + </term> + + <listitem> + <para> + Do not show the capture icon in the status bar. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Features</literal> + </term> + + <listitem> + <para> + Do not show the CPU features icon in the status bar. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Mouse</literal> + </term> + + <listitem> + <para> + Do not show the mouse icon in the status bar. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Keyboard</literal> + </term> + + <listitem> + <para> + Do not show the keyboard icon in the status bar. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM or global setting. Any combination of the above + is allowed. If all options are specified, no icons are displayed + in the status bar of the VM window. To restore the default + behavior, use + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedStatusBarIndicators</screen> + + </sect2> + + <sect2 id="config-vm-window-visual-modes"> + + <title>Configure VM Window Visual Modes</title> + + <para> + You can disable certain VM visual modes: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> GUI/RestrictedVisualStates <replaceable>property</replaceable>[,<replaceable>property</replaceable>...]</screen> + + <para> + <replaceable>property</replaceable> is one of the following: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>Fullscreen</literal> + </term> + + <listitem> + <para> + Do not allow to switch the VM into full screen mode. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Seamless</literal> + </term> + + <listitem> + <para> + Do not allow to switch the VM into seamless mode. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Scale</literal> + </term> + + <listitem> + <para> + Do not allow to switch the VM into scale mode. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM setting. You can specify any combination of + properties. To restore the default behavior, use the following + command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> GUI/RestrictedVisualStates</screen> + + </sect2> + + <sect2 id="host-key-customize"> + + <title>Host Key Customization</title> + + <para> + To disable all Host key combinations, open the preferences and + change the Host key to None. This might be useful when using + &product-name; in a kiosk mode. + </para> + + <para> + To redefine or disable certain Host key actions, use the + following command: + </para> + +<screen>$ VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=F,...."</screen> + + <para> + The following table shows the possible Host key actions, + together with their default Host key shortcut. Setting an action + to None will disable that Host key action. + </para> + + <table id="table-host-key-customize" tabstyle="oracle-all"> + <title>Host Key Customization</title> + <tgroup cols="3"> + <thead> + <row> + <entry><para> + <emphasis role="bold">Action</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Default Key</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Action</emphasis> + </para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para> + <literal>TakeSnapshot</literal> + </para></entry> + <entry><para> + T + </para></entry> + <entry><para> + Take a snapshot + </para></entry> + </row> + <row> + <entry><para> + <literal>TakeScreenshot</literal> + </para></entry> + <entry><para> + E + </para></entry> + <entry><para> + Take a screenshot + </para></entry> + </row> + <row> + <entry><para> + <literal>MouseIntegration</literal> + </para></entry> + <entry><para> + I + </para></entry> + <entry><para> + Toggle mouse integration + </para></entry> + </row> + <row> + <entry><para> + <literal>TypeCAD</literal> + </para></entry> + <entry><para> + Del + </para></entry> + <entry><para> + Inject Ctrl+Alt+Del + </para></entry> + </row> + <row> + <entry><para> + <literal>TypeCABS</literal> + </para></entry> + <entry><para> + Backspace + </para></entry> + <entry><para> + Inject Ctrl+Alt+Backspace + </para></entry> + </row> + <row> + <entry><para> + <literal>Pause</literal> + </para></entry> + <entry><para> + P + </para></entry> + <entry><para> + Pause the VM + </para></entry> + </row> + <row> + <entry><para> + <literal>Reset</literal> + </para></entry> + <entry><para> + R + </para></entry> + <entry>Hard reset the guest</entry> + </row> + <row> + <entry><para> + <literal>SaveState</literal> + </para></entry> + <entry><para></para></entry> + <entry><para> + Save the VM state and terminate the VM + </para></entry> + </row> + <row> + <entry><para> + <literal>Shutdown</literal> + </para></entry> + <entry><para> + H + </para></entry> + <entry><para> + Press the virtual ACPI power button + </para></entry> + </row> + <row> + <entry><para> + <literal>PowerOff</literal> + </para></entry> + <entry><para></para></entry> + <entry><para> + Power off the VM without saving the state + </para></entry> + </row> + <row> + <entry><para> + <literal>Close</literal> + </para></entry> + <entry><para> + Q + </para></entry> + <entry><para> + Show the Close VM dialog + </para></entry> + </row> + <row> + <entry><para> + <literal>FullscreenMode</literal> + </para></entry> + <entry><para> + F + </para></entry> + <entry><para> + Switch the VM into full screen mode + </para></entry> + </row> + <row> + <entry><para> + <literal>SeamlessMode</literal> + </para></entry> + <entry><para> + L + </para></entry> + <entry><para> + Switch the VM into seamless mode + </para></entry> + </row> + <row> + <entry><para> + <literal>ScaleMode</literal> + </para></entry> + <entry><para> + C + </para></entry> + <entry><para> + Switch the VM into scaled mode + </para></entry> + </row> + <row> + <entry><para> + <literal>GuestAutoResize</literal> + </para></entry> + <entry><para> + G + </para></entry> + <entry><para> + Automatically resize the guest window + </para></entry> + </row> + <row> + <entry><para> + <literal>WindowAdjust</literal> + </para></entry> + <entry><para> + A + </para></entry> + <entry><para> + Immediately resize the guest window + </para></entry> + </row> + <row> + <entry><para> + <literal>PopupMenu</literal> + </para></entry> + <entry><para> + Home + </para></entry> + <entry><para> + Show the popup menu in full screen mode and seamless + mode + </para></entry> + </row> + <row> + <entry><para> + <literal>SettingsDialog</literal> + </para></entry> + <entry><para> + S + </para></entry> + <entry><para> + Open the VM Settings dialog + </para></entry> + </row> + <row> + <entry><para> + <literal>InformationDialog</literal> + </para></entry> + <entry><para> + N + </para></entry> + <entry><para> + Show the VM Session Information window + </para></entry> + </row> + <row> + <entry><para> + <literal>NetworkAdaptersDialog</literal> + </para></entry> + <entry><para></para></entry> + <entry><para> + Show the VM Network Adapters dialog + </para></entry> + </row> + <row> + <entry><para> + <literal>SharedFoldersDialog</literal> + </para></entry> + <entry><para></para></entry> + <entry><para> + Show the VM Shared Folders dialog + </para></entry> + </row> + <row> + <entry><para> + <literal>InstallGuestAdditions</literal> + </para></entry> + <entry><para> + D + </para></entry> + <entry><para> + Mount the ISO containing the Guest Additions + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + To disable full screen mode and seamless mode, use the following + command: + </para> + +<screen>$ VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=None,SeamlessMode=None"</screen> + + </sect2> + + <sect2 id="terminate-vm-action"> + + <title>Action when Terminating the VM</title> + + <para> + You can disallow certain actions when terminating a VM. To + disallow specific actions, use the following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> GUI/RestrictedCloseActions <replaceable>property</replaceable>[,<replaceable>property</replaceable>...]</screen> + + <para> + <replaceable>property</replaceable> is one of the following: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>SaveState</literal> + </term> + + <listitem> + <para> + Do not allow the user to save the VM state when + terminating the VM. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Shutdown</literal> + </term> + + <listitem> + <para> + Do not allow the user to shutdown the VM by sending the + ACPI power-off event to the guest. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>PowerOff</literal> + </term> + + <listitem> + <para> + Do not allow the user to power off the VM. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>PowerOffRestoringSnapshot</literal> + </term> + + <listitem> + <para> + Do not allow the user to return to the last snapshot when + powering off the VM. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Detach</literal> + </term> + + <listitem> + <para> + Do not allow the user to detach from the VM process if the + VM was started in separate mode. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM setting. You can specify any combination of + properties. If all properties are specified, the VM cannot be + shut down. + </para> + + </sect2> + + <sect2 id="terminate-vm-default-action"> + + <title>Default Action when Terminating the VM</title> + + <para> + You can define a specific action for terminating a VM. In + contrast to the setting decribed in the previous section, this + setting allows only one action when the user terminates the VM. + No exit menu is shown. Use the following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> GUI/DefaultCloseAction <replaceable>action</replaceable></screen> + + <para> + <replaceable>action</replaceable> is one of the following: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>SaveState</literal> + </term> + + <listitem> + <para> + Save the VM state before terminating the VM process. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Shutdown</literal> + </term> + + <listitem> + <para> + The VM is shut down by sending the ACPI power-off event to + the guest. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>PowerOff</literal> + </term> + + <listitem> + <para> + The VM is powered off. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>PowerOffRestoringSnapshot</literal> + </term> + + <listitem> + <para> + The VM is powered off and the saved state returns to the + last snapshot. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Detach</literal> + </term> + + <listitem> + <para> + Terminate the frontend but leave the VM process running. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM setting. You can specify any combination of + properties. If all properties are specified, the VM cannot be + shut down. + </para> + + </sect2> + + <sect2 id="guru-meditation-action"> + + <title>Action for Handling a Guru Meditation</title> + + <para> + A VM runs into a Guru Meditation if there is a problem which + cannot be fixed by other means than terminating the process. The + default is to show a message window which instructs the user to + open a bug report. + </para> + + <para> + This behavior can be configured as follows: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> GUI/GuruMeditationHandler <replaceable>mode</replaceable></screen> + + <para> + <replaceable>mode</replaceable> is one of the following: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>Default</literal> + </term> + + <listitem> + <para> + A message window is shown. After the user confirmed, the + VM is terminated. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>PowerOff</literal> + </term> + + <listitem> + <para> + The VM is immediately powered-off without showing any + message window. The VM logfile will show information about + what happened. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Ignore</literal> + </term> + + <listitem> + <para> + The VM is left in stuck mode. Execution is stopped but no + message window is shown. The VM has to be powered off + manually. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM setting. + </para> + + </sect2> + + <sect2 id="mouse-capture"> + + <title>Configuring Automatic Mouse Capturing</title> + + <para> + By default, the mouse is captured if the user clicks on the + guest window and the guest expects relative mouse coordinates at + this time. This happens if the pointing device is configured as + PS/2 mouse and the guest has not yet started the &product-name; + Guest Additions. For instance, the guest is booting or the Guest + Additions are not installed, or if the pointing device is + configured as a USB tablet but the guest has no USB driver + loaded yet. Once the Guest Additions become active or the USB + guest driver is started, the mouse capture is automatically + released. + </para> + + <para> + The default behavior is sometimes not desired. Therefore it can + be configured as follows: + </para> + +<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> GUI/MouseCapturePolicy <replaceable>mode</replaceable></screen> + + <para> + <replaceable>mode</replaceable> is one of the following: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>Default</literal> + </term> + + <listitem> + <para> + The default behavior as described above. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>HostComboOnly</literal> + </term> + + <listitem> + <para> + The mouse is only captured if the Host Key is toggled. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Disabled</literal> + </term> + + <listitem> + <para> + The mouse is never captured, also not by toggling the Host + Key + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM setting. + </para> + + </sect2> + + <sect2 id="legacy-fullscreen-mode"> + + <title>Requesting Legacy Full-Screen Mode</title> + + <para> + &product-name; uses special window manager facilities to switch + a multi-screen machine to full-screen on a multi-monitor host + system. However, not all window managers provide these + facilities correctly. &product-name; can be configured to use a + legacy method of switching to full-screen mode instead, by using + the command: + </para> + +<screen>VBoxManage setextradata global GUI/Fullscreen/LegacyMode true</screen> + + <para> + You can go back to the default method by using the following + command: + </para> + +<screen>VBoxManage setextradata global GUI/Fullscreen/LegacyMode</screen> + + <para> + This is a global setting. + </para> + + </sect2> + + <sect2 id="restrict-network-attachments"> + + <title>Removing Certain Modes of Networking From the GUI</title> + + <para> + It is possible to remove networking modes from &product-name; + GUI. To do this, use the following command: + </para> + +<screen>VBoxManage setextradata global GUI/RestrictedNetworkAttachmentTypes <replaceable>property</replaceable>[,<replaceable>property</replaceable>...]</screen> + + <para> + <replaceable>property</replaceable> is one of the following: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>NAT</literal> + </term> + + <listitem> + <para> + Remove the <emphasis role="bold">NAT</emphasis> option + from the GUI. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>NATNetwork</literal> + </term> + + <listitem> + <para> + Remove the <emphasis role="bold">NAT network</emphasis> + option from the GUI. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>BridgedAdapter</literal> + </term> + + <listitem> + <para> + Remove the <emphasis role="bold">Bridged + networking</emphasis> option from the GUI. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>InternalNetwork</literal> + </term> + + <listitem> + <para> + Remove the <emphasis role="bold">Internal + networking</emphasis> option from the GUI. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>HostOnlyAdapter</literal> + </term> + + <listitem> + <para> + Remove the <emphasis role="bold">Host Only + networking</emphasis> option from the GUI. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>GenericDriver</literal> + </term> + + <listitem> + <para> + Remove the <emphasis role="bold">Generic + networking</emphasis> option from the GUI. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a global setting. You can specify any combination of + properties. To restore the default behavior, use the following + command: + </para> + +<screen>VBoxManage setextradata global GUI/RestrictedNetworkAttachmentTypes</screen> + + </sect2> + + </sect1> + + <sect1 id="vboxwebsrv-daemon"> + + <title>Starting the &product-name; Web Service Automatically</title> + + <para> + The &product-name; web service, <command>vboxwebsrv</command>, is + used for controlling &product-name; remotely. It is documented in + detail in the &product-name; Software Development Kit (SDK). See + <xref linkend="VirtualBoxAPI" />. Web service start scripts are + available for supported host operating systems. The following + sections describe how to use the scripts. The &product-name; web + service is never started automatically as a result of a standard + installation. + </para> + + <sect2 id="vboxwebsrv-linux"> + + <title>Linux: Starting the Web Service With init</title> + + <para> + On Linux, the web service can be automatically started during + host boot by adding appropriate parameters to the file + <filename>/etc/default/virtualbox</filename>. There is one + mandatory parameter, <literal>VBOXWEB_USER</literal>, which must + be set to the user which will later start the VMs. The + parameters in the following table all start with the + <literal>VBOXWEB_</literal> prefix string. For example: + <literal>VBOXWEB_HOST</literal> and + <literal>VBOXWEB_PORT</literal>. + </para> + + <table id="table-websrv-config-params" tabstyle="oracle-all"> + <title>Web Service Configuration Parameters</title> + <tgroup cols="3"> + <thead> + <row> + <entry><para> + <emphasis role="bold">Parameter</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Description</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Default</emphasis> + </para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para> + <literal>USER</literal> + </para></entry> + <entry><para> + The user which the web service runs as + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + <literal>HOST</literal> + </para></entry> + <entry><para> + The host to bind the web service to + </para></entry> + <entry><para> + localhost + </para></entry> + </row> + <row> + <entry><para> + <literal>PORT</literal> + </para></entry> + <entry><para> + The port to bind the web service to + </para></entry> + <entry><para> + 18083 + </para></entry> + </row> + <row> + <entry><para> + <literal>SSL_KEYFILE</literal> + </para></entry> + <entry><para> + Server key and certificate file, in PEM format + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + <literal>SSL_PASSWORDFILE</literal> + </para></entry> + <entry><para> + File name for password to server key + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + <literal>SSL_CACERT</literal> + </para></entry> + <entry><para> + CA certificate file, in PEM format + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + <literal>SSL_CAPATH</literal> + </para></entry> + <entry><para> + CA certificate path + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + <literal>SSL_DHFILE</literal> + </para></entry> + <entry><para> + DH file name or DH key length in bits + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + <literal>SSL_RANDFILE</literal> + </para></entry> + <entry><para> + File containing seed for random number generator + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + <literal>TIMEOUT</literal> + </para></entry> + <entry><para> + Session timeout in seconds, 0 disables timeouts + </para></entry> + <entry><para> + 300 + </para></entry> + </row> + <row> + <entry><para> + <literal>CHECK_INTERVAL</literal> + </para></entry> + <entry><para> + Frequency of timeout checks in seconds + </para></entry> + <entry><para> + 5 + </para></entry> + </row> + <row> + <entry><para> + <literal>THREADS</literal> + </para></entry> + <entry><para> + Maximum number of worker threads to run in parallel + </para></entry> + <entry><para> + 100 + </para></entry> + </row> + <row> + <entry><para> + <literal>KEEPALIVE</literal> + </para></entry> + <entry><para> + Maximum number of requests before a socket will be + closed + </para></entry> + <entry><para> + 100 + </para></entry> + </row> + <row> + <entry><para> + <literal>ROTATE</literal> + </para></entry> + <entry><para> + Number of log files, 0 disables log rotation + </para></entry> + <entry><para> + 10 + </para></entry> + </row> + <row> + <entry><para> + <literal>LOGSIZE</literal> + </para></entry> + <entry><para> + Maximum log file size to trigger rotation, in bytes + </para></entry> + <entry><para> + 1MB + </para></entry> + </row> + <row> + <entry><para> + <literal>LOGINTERVAL</literal> + </para></entry> + <entry><para> + Maximum time interval to trigger log rotation, in + seconds + </para></entry> + <entry><para> + 1 day + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + Setting the parameter <literal>SSL_KEYFILE</literal> enables the + SSL/TLS support. Using encryption is strongly encouraged, as + otherwise everything, including passwords, is transferred in + clear text. + </para> + + </sect2> + + <sect2 id="vboxwebsrv-solaris"> + + <title>Oracle Solaris: Starting the Web Service With SMF</title> + + <para> + On Oracle Solaris hosts, the &product-name; web service daemon + is integrated into the SMF framework. You can change the + parameters, but do not have to if the defaults below already + match your needs: + </para> + +<screen>svccfg -s svc:/application/virtualbox/webservice:default setprop config/host=localhost +svccfg -s svc:/application/virtualbox/webservice:default setprop config/port=18083 +svccfg -s svc:/application/virtualbox/webservice:default setprop config/user=root</screen> + + <para> + The table in <xref linkend="vboxwebsrv-linux"/> showing the + parameter names and defaults also applies for Oracle Solaris. + The parameter names must be changed to lowercase and a prefix of + <literal>config/</literal> has to be added. For example: + <literal>config/user</literal> or + <literal>config/ssl_keyfile</literal>. If you make any change, + do not forget to run the following command to put the changes + into effect immediately: + </para> + +<screen>svcadm refresh svc:/application/virtualbox/webservice:default</screen> + + <para> + If you forget the above command then the previous settings are + used when enabling the service. Check the current property + settings as follows: + </para> + +<screen>svcprop -p config svc:/application/virtualbox/webservice:default</screen> + + <para> + When everything is configured correctly you can start the + &product-name; web service with the following command: + </para> + +<screen>svcadm enable svc:/application/virtualbox/webservice:default</screen> + + <para> + For more information about SMF, please refer to the Oracle + Solaris documentation. + </para> + + </sect2> + + <sect2 id="vboxwebsrv-osx"> + + <title>macOS: Starting the Web Service With launchd</title> + + <para> + On macOS, launchd is used to start the &product-name; + webservice. An example configuration file can be found in + <filename>$HOME/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</filename>. + It can be enabled by changing the <literal>Disabled</literal> + key from <literal>true</literal> to <literal>false</literal>. To + manually start the service use the following command: + </para> + +<screen>launchctl load ~/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</screen> + + <para> + For additional information on how launchd services could be + configured see: + </para> + + <para> + <ulink + url="https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html" />. + </para> + + </sect2> + + </sect1> + + <sect1 id="vboxwatchdog"> + + <title>&product-name; Watchdog</title> + + <para> + The memory ballooning service, formerly known as + <command>VBoxBalloonCtrl</command>, was renamed to VBoxWatchdog. + This service now incorporates the following host services that are + meant to be run in a server environment: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Memory ballooning control.</emphasis> + This service automatically takes care of a VM's configured + memory balloon. See <xref linkend="guestadd-balloon" />. This + service is useful for server environments where VMs may + dynamically require more or less memory during runtime. + </para> + + <para> + The service periodically checks a VM's current memory balloon + and its free guest RAM and automatically adjusts the current + memory balloon by inflating or deflating it accordingly. This + handling only applies to running VMs having recent Guest + Additions installed. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Host isolation detection.</emphasis> + This service provides a way to detect whether the host cannot + reach the specific &product-name; server instance anymore and + take appropriate actions, such as shutting down, saving the + current state or even powering down certain VMs. + </para> + </listitem> + + </itemizedlist> + + <para> + All configuration values can be either specified using the command + line or global extradata, whereas command line values always have + a higher priority when set. Some of the configuration values also + be specified on a per-VM basis. So the overall lookup order is: + command line, per-VM basis extradata if available, global + extradata. + </para> + + <sect2 id="vboxwatchdog-ballonctrl"> + + <title>Memory Ballooning Control</title> + + <para> + The memory ballooning control inflates and deflates the memory + balloon of VMs based on the VMs free memory and the desired + maximum balloon size. + </para> + + <para> + To set up the memory ballooning control the maximum ballooning + size a VM can reach needs to be set. This can be specified using + the command line, as follows: + </para> + +<screen>--balloon-max <Size in MB></screen> + + <para> + Using a per-VM basis extradata value, as follows: + </para> + +<screen>VBoxManage setextradata <VM-Name> VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax <Size in MB></screen> + + <para> + Using a global extradata value, as follows: + </para> + +<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax <Size in MB></screen> + + <note> + <para> + If no maximum ballooning size is specified by at least one of + the parameters above, no ballooning will be performed at all. + </para> + </note> + + <para> + Setting the ballooning increment in MB can be either done using + command line, as follows: + </para> + +<screen>--balloon-inc <Size in MB></screen> + + <para> + Using a global extradata value, as follows: + </para> + +<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonIncrementMB <Size in MB></screen> + + <para> + The default ballooning increment is 256 MB if not specified. + </para> + + <para> + The same options apply for a ballooning decrement. Using the + command line, as follows: + </para> + +<screen>--balloon-dec <Size in MB></screen> + + <para> + Using a global extradata value, as follows: + </para> + +<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonDecrementMB <Size in MB></screen> + + <para> + The default ballooning decrement is 128 MB if not specified. + </para> + + <para> + The lower limit in MB for a balloon can be defined using the + command line, as follows: + </para> + +<screen>--balloon-lower-limit <Size in MB></screen> + + <para> + Using a global extradata value, as follows: + </para> + +<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonLowerLimitMB <Size in MB></screen> + + <para> + The default lower limit is 128 MB if not specified. + </para> + + </sect2> + + <sect2 id="vboxwatchdog-hostisln"> + + <title>Host Isolation Detection</title> + + <para> + To detect whether a host is being isolated, that is, the host + cannot reach the &product-name; server instance anymore, the + host needs to set an alternating value to a global extradata + value within a time period. If this value is not set within that + time period a timeout occurred and the so-called host isolation + response will be performed to the VMs handled. Which VMs are + handled can be controlled by defining VM groups and assigning + VMs to those groups. By default no groups are set, meaning that + all VMs on the server will be handled when no host response is + received within 30 seconds. + </para> + + <para> + Set the groups handled by the host isolation detection using the + following command line: + </para> + +<screen>--apimon-groups=<string[,stringN]></screen> + + <para> + Using a global extradata value, as follows: + </para> + +<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/Groups <string[,stringN]></screen> + + <para> + Set the host isolation timeout using the following command line: + </para> + +<screen>--apimon-isln-timeout=<ms></screen> + + <para> + Using a global extradata value, as follows: + </para> + +<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationTimeoutMS <ms></screen> + + <para> + Set the actual host isolation response using the following + command line: + </para> + +<screen>--apimon-isln-response=<cmd></screen> + + <para> + Using a global extradata value, as follows: + </para> + +<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationResponse <cmd></screen> + + <para> + The following response commands are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <literal>none</literal>. This has no effect. + </para> + </listitem> + + <listitem> + <para> + <literal>pause</literal>. Pauses the execution of a VM. + </para> + </listitem> + + <listitem> + <para> + <literal>poweroff</literal>. Shuts down the VM by pressing + the virtual power button. The VM will not have the chance of + saving any data or veto the shutdown process. + </para> + </listitem> + + <listitem> + <para> + <literal>save</literal>. Saves the current machine state and + powers off the VM afterwards. If saving the machine state + fails the VM will be paused. + </para> + </listitem> + + <listitem> + <para> + <literal>shutdown</literal>. Shuts down the VM in a gentle + way by sending an <literal>ACPI</literal> shutdown event to + the VM's operating system. The OS then has the chance of + doing a clean shutdown. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="vboxwatchdog-moreinfo"> + + <title>More Information</title> + + <para> + For more advanced options and parameters like verbose logging + check the built-in command line help accessible with + <option>--help</option>. + </para> + + </sect2> + + <sect2 id="vboxwatchdog-linux"> + + <title>Linux: Starting the Watchdog Service With init</title> + + <para> + On Linux, the watchdog service can be automatically started + during host boot by adding appropriate parameters to the file + <filename>/etc/default/virtualbox</filename>. There is one + mandatory parameter, <literal>VBOXWATCHDOG_USER</literal>, which + must be set to the user which will later start the VMs. For + backward compatibility you can also specify + <literal>VBOXBALLOONCTRL_USER</literal>. + </para> + + <para> + The parameters in the following table all start with the + <literal>VBOXWATCHDOG_</literal> prefix string. For example: + <literal>VBOXWATCHDOG_BALLOON_INTERVAL</literal> and + <literal>VBOXWATCHDOG_LOGSIZE</literal>. Legacy parameters such + as <literal>VBOXBALLOONCTRL_INTERVAL</literal> can still be + used. + </para> + + <table id="table-vboxwatchdog-config-params" tabstyle="oracle-all"> + <title>&product-name; Watchdog Configuration Parameters</title> + <tgroup cols="3"> + <thead> + <row> + <entry><para> + <emphasis role="bold">Parameter</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Description</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Default</emphasis> + </para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para> + <literal>USER</literal> + </para></entry> + <entry><para> + The user which the watchdog service runs as + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + <literal>ROTATE</literal> + </para></entry> + <entry><para> + Number of log files, 0 disables log rotation + </para></entry> + <entry><para> + 10 + </para></entry> + </row> + <row> + <entry><para> + <literal>LOGSIZE</literal> + </para></entry> + <entry><para> + Maximum log file size to trigger rotation, in bytes + </para></entry> + <entry><para> + 1MB + </para></entry> + </row> + <row> + <entry><para> + <literal>LOGINTERVAL</literal> + </para></entry> + <entry><para> + Maximum time interval to trigger log rotation, in + seconds + </para></entry> + <entry><para> + 1 day + </para></entry> + </row> + <row> + <entry><para> + <literal>BALLOON_INTERVAL</literal> + </para></entry> + <entry><para> + Interval for checking the balloon size, in + milliseconds + </para></entry> + <entry><para> + 30000 + </para></entry> + </row> + <row> + <entry><para> + <literal>BALLOON_INCREMENT</literal> + </para></entry> + <entry><para> + Balloon size increment, in megabytes + </para></entry> + <entry><para> + 256 + </para></entry> + </row> + <row> + <entry><para> + <literal>BALLOON_DECREMENT</literal> + </para></entry> + <entry><para> + Balloon size decrement, in megabytes + </para></entry> + <entry><para> + 128 + </para></entry> + </row> + <row> + <entry><para> + <literal>BALLOON_LOWERLIMIT</literal> + </para></entry> + <entry><para> + Balloon size lower limit, in megabytes + </para></entry> + <entry><para> + 64 + </para></entry> + </row> + <row> + <entry><para> + <literal>BALLOON_SAFETYMARGIN</literal> + </para></entry> + <entry><para> + Free memory required for decreasing the balloon size, + in megabytes + </para></entry> + <entry><para> + 1024 + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + </sect2> + + <sect2 id="vboxwatchdog-solaris"> + + <title>Oracle Solaris: Starting the Watchdog Service With SMF</title> + + <para> + On Oracle Solaris hosts, the &product-name; watchdog service + daemon is integrated into the SMF framework. You can change the + parameters, but do not have to if the defaults already match + your needs: + </para> + +<screen>svccfg -s svc:/application/virtualbox/balloonctrl:default setprop \ + config/balloon_interval=10000 +svccfg -s svc:/application/virtualbox/balloonctrl:default setprop \ +config/balloon_safetymargin=134217728</screen> + + <para> + <xref linkend="table-vboxwatchdog-config-params"/> also applies + for Oracle Solaris. The parameter names must be changed to + lowercase and a prefix of <literal>config/</literal> has to be + added. For example: <literal>config/user</literal> or + <literal>config/balloon_safetymargin</literal>. If you made any + change, do not forget to run the following command to put the + changes into effect immediately: + </para> + +<screen>svcadm refresh svc:/application/virtualbox/balloonctrl:default</screen> + + <para> + If you forget the above command then the previous settings will + be used when enabling the service. Check the current property + settings with the following command: + </para> + +<screen>svcprop -p config svc:/application/virtualbox/balloonctrl:default</screen> + + <para> + When everything is configured correctly you can start the + &product-name; watchdog service with the following command: + </para> + +<screen>svcadm enable svc:/application/virtualbox/balloonctrl:default</screen> + + <para> + For more information about SMF, please refer to the Oracle + Solaris documentation. + </para> + + </sect2> + + </sect1> + + <sect1 id="otherextpacks"> + + <title>Other Extension Packs</title> + + <para> + Another extension pack called VNC is available. This extension + pack is open source and replaces the previous integration of the + VNC remote access protocol. This is experimental code, and is + initially available in the &product-name; source code package + only. It is to a large portion code contributed by users, and is + not supported in any way by Oracle. + </para> + + <para> + The keyboard handling is severely limited, and only the US + keyboard layout works. Other keyboard layouts will have at least + some keys which produce the wrong results, often with quite + surprising effects, and for layouts which have significant + differences to the US keyboard layout it is most likely unusable. + </para> + + <para> + It is possible to install both the &product-name; Extension Pack + and VNC, but only one VRDE module can be active at any time. The + following command switches to the VNC VRDE module in VNC: + </para> + +<screen>VBoxManage setproperty vrdeextpack VNC</screen> + + <para> + Configuring the remote access works very similarly to VRDP, see + <xref linkend="vrde" />, with some limitations. VNC does not + support specifying several port numbers, and the authentication is + done differently. VNC can only deal with password authentication, + and there is no option to use password hashes. This leaves no + other choice than having a clear-text password in the VM + configuration, which can be set with the following command: + </para> + +<screen>VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property VNCPassword=secret</screen> + + <para> + The user is responsible for keeping this password secret, and it + should be removed when a VM configuration is passed to another + person, for whatever purpose. Some VNC servers claim to have + encrypted passwords in the configuration. This is not true + encryption, it is only concealing the passwords, which is only as + secure as using clear-text passwords. + </para> + + <para> + The following command switches back to VRDP, if installed: + </para> + +<screen>VBoxManage setproperty vrdeextpack "&product-name; Extension Pack"</screen> + + </sect1> + + <sect1 id="autostart"> + + <title>Starting Virtual Machines During System Boot</title> + + <para> + You can start VMs automatically during system boot on Linux, + Oracle Solaris, and macOS platforms for all users. + </para> + + <sect2 id="autostart-linux"> + + <title>Linux: Starting the Autostart Service With init</title> + + <para> + On Linux, the autostart service is activated by setting two + variables in <filename>/etc/default/virtualbox</filename>. The + first one is <literal>VBOXAUTOSTART_DB</literal> which contains + an absolute path to the autostart database directory. The + directory should have write access for every user who should be + able to start virtual machines automatically. Furthermore the + directory should have the sticky bit set. The second variable is + <literal>VBOXAUTOSTART_CONFIG</literal> which points the service + to the autostart configuration file which is used during boot to + determine whether to allow individual users to start a VM + automatically and configure startup delays. The configuration + file can be placed in <filename>/etc/vbox</filename> and + contains several options. One is + <literal>default_policy</literal> which controls whether the + autostart service allows or denies to start a VM for users which + are not in the exception list. The exception list starts with + <literal>exception_list</literal> and contains a comma separated + list with usernames. Furthermore a separate startup delay can be + configured for every user to avoid overloading the host. A + sample configuration is given below: + </para> + +<screen> +# Default policy is to deny starting a VM, the other option is "allow". +default_policy = deny + +# Bob is allowed to start virtual machines but starting them +# will be delayed for 10 seconds +bob = { + allow = true + startup_delay = 10 +} + +# Alice is not allowed to start virtual machines, useful to exclude certain users +# if the default policy is set to allow. +alice = { + allow = false +} +</screen> + + <para> + Any user who wants to enable autostart for individual machines + must set the path to the autostart database directory with the + following command: + </para> + +<screen>VBoxManage setproperty autostartdbpath <replaceable>autostart-directory</replaceable></screen> + + </sect2> + + <sect2 id="autostart-solaris"> + + <title>Oracle Solaris: Starting the Autostart Service With SMF</title> + + <para> + On Oracle Solaris hosts, the &product-name; autostart daemon is + integrated into the SMF framework. To enable it you must point + the service to an existing configuration file which has the same + format as on Linux, see <xref linkend="autostart-linux" />. For + example: + </para> + +<screen># svccfg -s svc:/application/virtualbox/autostart:default setprop \ + config/config=/etc/vbox/autostart.cfg</screen> + + <para> + When everything is configured correctly you can start the + &product-name; autostart service with the following command: + </para> + +<screen># svcadm enable svc:/application/virtualbox/autostart:default</screen> + + <para> + For more information about SMF, see the Oracle Solaris + documentation. + </para> + + </sect2> + + <sect2 id="autostart-osx"> + + <title>macOS: Starting the Autostart Service With launchd</title> + + <para> + On macOS, launchd is used to start the &product-name; autostart + service. An example configuration file can be found in + <filename>/Applications/VirtualBox.app/Contents/MacOS/org.virtualbox.vboxautostart.plist</filename>. + To enable the service copy the file to + <filename>/Library/LaunchDaemons</filename> and change the + <literal>Disabled</literal> key from <literal>true</literal> to + <literal>false</literal>. Furthermore replace the second + parameter to an existing configuration file which has the same + format as on Linux, see <xref linkend="autostart-linux" />. + </para> + + <para> + To manually start the service use the following command: + </para> + +<screen># launchctl load /Library/LaunchDaemons/org.virtualbox.vboxautostart.plist</screen> + + <para> + For additional information on how launchd services can be + configured see: + </para> + + <para> + <ulink + url="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html" />. + </para> + + </sect2> + + <sect2 id="autostart-windows"> + + <title>Windows: Starting the Autostart Service</title> + + <para> + On Windows, autostart functionality consist of two components. + The first component is a configuration file where the + administrator can both set a delayed start for the VMs and + temporarily disable autostarting for a particular user. The + configuration file should be located in a folder accessible by + all required users but it should have permissions allowing only + reading by everyone but administrators. The configuration file + contains several options. The <literal>default_policy</literal> + controls whether the autostart service allows or denies starting + of a VM for users that are not in the exception list. The + exception list starts with <literal>exception_list</literal> and + contains a comma separated list with usernames. Furthermore, a + separate startup delay can be configured for every user to avoid + overloading the host. A sample configuration is given below: + </para> + +<screen> + # Default policy is to deny starting a VM, the other option is "allow". + default_policy = deny + + # Bob is allowed to start virtual machines but starting them + # will be delayed for 10 seconds + bob = { + allow = true + startup_delay = 10 + } + + # Alice is not allowed to start virtual machines, useful to exclude certain users + # if the default policy is set to allow. + alice = { + allow = false + } +</screen> + + <para> + The user name can be specified using the following forms: + "user", "domain\user", ".\user" and "user@domain". An + administrator must add the + <literal>VBOXAUTOSTART_CONFIG</literal> environment variable + into system variables containing the path to the configuration + file described above. The environment variable tells the + autostart services which configuration file is used. + </para> + + <para> + The second component of autostart functionality is a Windows + service. Every instance of this works on behalf of a particular + user using their credentials. + </para> + + <para> + To enable autostarting for a particular user, a member of the + administrators group must run the following command: + </para> + +<screen>VBoxAutostartSvc install --user=<replaceable>user</replaceable> [--password-file=<replaceable>password_file</replaceable>]</screen> + + <para> + The password file should contain the password followed by a line + break. The rest of the file is ignored. The user will be asked + for a password if the password file is not specified. + </para> + + <para> + To disable autostarting for particular user, a member of the + administrators group must run the following command: + </para> + +<screen>VBoxAutostartSvc delete --user=<replaceable>user</replaceable></screen> + + <para> + If a user has changed their password then a member of the + administrators group must either reinstall the service or change + the service credentials using Windows Service Manager. Due to + Windows security policies, the autostart service cannot be + installed for users with empty passwords. + </para> + + <para> + Finally, the user should define which VMs should be started at + boot. The user should run the following command for every VM + they wish to start at boot: + </para> + +<screen>VBoxManage modifyvm <replaceable>VM name or UUID</replaceable> --autostart-enabled on</screen> + + <para> + The user can remove a particular VM from the VMs starting at + boot by running the following command: + </para> + +<screen>VBoxManage modifyvm <replaceable>VM name or UUID</replaceable> --autostart-enabled off</screen> + + <note> + <para> + On Windows hosts, starting VMs via the autostart service might + cause some issues, as the virtual machines are starting within + the same session as VBoxSVC. For more information see + <xref linkend="vboxsvc-session-0" />. + </para> + </note> + + </sect2> + + </sect1> + + <sect1 id="vmencryption"> + + <title>Encryption of VMs</title> + + <para> + &product-name; enables you to transparently encrypt the VM data + stored in the configuration file, saved state, and EFI boot data + for the guest. + </para> + + <para> + &product-name; uses the AES algorithm in various modes. The + selected mode depends on the encrypting component of the VM. + &product-name; supports 128-bit or 256-bit data encryption keys + (DEK). The DEK is stored encrypted in the VM configuration file + and is decrypted during VM startup. + </para> + + <para> + Since the DEK is stored as part of the VM configuration file, it + is important that the file is kept safe. Losing the DEK means that + the data stored in the VM is lost irrecoverably. Having complete + and up to date backups of all data related to the VM is the + responsibility of the user. + </para> + + <para> + The VM, even if it is encrypted, may contain media encrypted with + different passwords. To deal with this, the password for the VM + has a password identifier, in the same way as passwords for media. + The password ID is an arbitrary string which uniquely identifies + the password in the VM and its media. You can use the same + password and ID for both the VM and its media. + </para> + + <sect2 id="vmencryption-limitations"> + + <title>Limitations of VM Encryption</title> + + <para> + There are some limitations the user needs to be aware of when + using this feature: + </para> + + <itemizedlist> + + <listitem> + <para> + Exporting appliances containing an encrypted VM is not + possible, because the OVF specification does not support + this. The VM is therefore decrypted during export. + </para> + </listitem> + + <listitem> + <para> + The DEK is kept in memory while the VM is running to be able + to encrypt and decrypt VM data. While this should be obvious + the user needs to be aware of this because an attacker might + be able to extract the key on a compromised host and decrypt + the data. + </para> + </listitem> + + <listitem> + <para> + When encrypting or decrypting the VM, the password is passed + in clear text using the &product-name; API. This needs to be + kept in mind, especially when using third party API clients + which make use of the web service where the password might + be transmitted over the network. The use of HTTPS is + mandatory in such a case. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="vmencryption-encryption"> + + <title>Encrypting a VM</title> + + <para> + Encrypting a VM can be done either using &vbox-mgr; or the + <command>VBoxManage</command>. To encrypt an unencrypted VM with + <command>VBoxManage</command>, use: + </para> + +<screen>VBoxManage encryptvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> setencryption --new-password <replaceable>filename</replaceable>|- \ +--cipher <replaceable>cipher-ID</replaceable> --new-password-id <replaceable>ID</replaceable></screen> + + <para> + To supply the encryption password, point + <command>VBoxManage</command> to the file where the password is + stored or specify <option>-</option> to let + <command>VBoxManage</command> prompt for the password on the + command line. + </para> + + <para> + The cipher parameter specifies the cipher to use for encryption + and can be either <literal>AES-128</literal> or + <literal>AES-256</literal>. The appropriate mode of operation, + such as GCM, CTR, or XTS will be selected by the VM depending on + the encrypting component. The specified password identifier can + be freely chosen by the user and is used for correct + identification when supplying multiple passwords for the VM. + </para> + + </sect2> + + <sect2 id="vmencryption-addpassword"> + + <title>Opening the Encrypted VM</title> + + <para> + When &product-name; has just started up the encrypted VM cannot + be opened and it stays inaccessible. Also, the encrypted VM + stays inaccessible if it was just registered without a password + or the password is incorrect. The user needs to provide the + password using &vbox-mgr; or with the following + <command>VBoxManage</command> command: + </para> + +<screen>VBoxManage encryptvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> addpassword --password <replaceable>filename</replaceable>|- --password-id <replaceable>ID</replaceable></screen> + + <para> + To supply the encryption password point + <command>VBoxManage</command> to the file where the password is + stored or specify <option>-</option> to let + <command>VBoxManage</command> prompt for the password on the + command line. + </para> + + <para> + If <replaceable>ID</replaceable> is the same as the password + identifier supplied when encrypting the VM it updates the + accessibility state. + </para> + + <para> + To remove the entered password from the VM memory, use + <command>VBoxManage</command> as follows: + </para> + +<screen>VBoxManage encryptvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> removepassword <replaceable>ID</replaceable></screen> + + <para> + If <replaceable>ID</replaceable> is the same as the password + identifier supplied when encrypting the VM it updates the + accessibility state. + </para> + + <note> + <para> + If a machine becomes inaccessible all passwords are purged. + You have to add required passwords again, using the + <command>VBoxManage encryptvm + <replaceable>vmname</replaceable> addpassword</command> + command. See <xref linkend="vmencryption-addpassword" />. + </para> + </note> + + </sect2> + + <sect2 id="vmencryption-decryption"> + + <title>Decrypting Encrypted VMs</title> + + <para> + In some circumstances it might be required to decrypt previously + encrypted VMs. This can be done in &vbox-mgr; or using + <command>VBoxManage</command> with the following command: + </para> + +<screen>VBoxManage encryptvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> setencryption --old-password <replaceable>file</replaceable>|-</screen> + + <para> + The only required parameter is the password the VM was encrypted + with. The options are the same as for encrypting VMs. + </para> + + </sect2> + + </sect1> + + <sect1 id="vboxexpertstoragemgmt"> + + <title>&product-name; Expert Storage Management</title> + + <para> + In case the snapshot model of &product-name; is not sufficient it + is possible to enable a special mode which makes it possible to + reconfigure storage attachments while the VM is paused. The user + has to make sure that the disk data stays consistent to the guest + because unlike with hotplugging the guest is not informed about + detached or newly attached media. + </para> + + <para> + The expert storage management mode can be enabled per VM + executing: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal2/SilentReconfigureWhilePaused" 1</screen> + + <para> + You can reconfigure storage attachments later while the VM is + paused by using the <command>VBoxManage storageattach</command> + command. + </para> + + </sect1> + + <sect1 id="hostpowertweaks"> + + <title>Handling of Host Power Management Events</title> + + <para> + Some host power management events are handled by &product-name;. + The actual behavior depends on the platform: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Host Suspends.</emphasis> This event is + generated when the host is about to suspend, that is, the host + saves the state to some non-volatile storage and powers off. + </para> + + <para> + This event is currently only handled on Windows hosts and Mac + OS X hosts. When this event is generated, &product-name; will + pause all running VMs. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Host Resumes.</emphasis> This event is + generated when the host woke up from the suspended state. + </para> + + <para> + This event is currently only handled on Windows hosts and Mac + OS X hosts. When this event is generated, &product-name; will + resume all VMs which are where paused before. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Battery Low.</emphasis> The battery + level reached a critical level, usually less than 5 percent + charged. + </para> + + <para> + This event is currently only handled on Windows hosts and Mac + OS X hosts. When this event is generated, &product-name; will + save the state and terminate all VMs in preparation of a + potential host powerdown. + </para> + + <para> + The behavior can be configured. By executing the following + command, no VM is saved: + </para> + +<screen>$ VBoxManage setextradata global "VBoxInternal2/SavestateOnBatteryLow" 0</screen> + + <para> + This is a global setting as well as a per-VM setting. The + per-VM value has higher precedence than the global value. The + following command will save the state of all VMs but will not + save the state of VM "foo": + </para> + +<screen>$ VBoxManage setextradata global "VBoxInternal2/SavestateOnBatteryLow" 1 +$ VBoxManage setextradata "foo" "VBoxInternal2/SavestateOnBatteryLow" 0</screen> + + <para> + The first line is actually not required as by default the + savestate action is performed. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="sse412passthrough"> + + <title>Passing Through SSE4.1/SSE4.2 Instructions</title> + + <para> + To provide SSE 4.1/SSE 4.2 support to guests, the host CPU has to + implement these instruction sets. The instruction sets are exposed + to guests by default, but it is possible to disable the + instructions for certain guests by using the following commands: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/CPUM/IsaExts/SSE4.1 0 +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/CPUM/IsaExts/SSE4.2 0</screen> + + <para> + These are per-VM settings which are enabled by default. + </para> + + </sect1> + + <sect1 id="hidledssync"> + + <title>Support for Keyboard Indicator Synchronization</title> + + <para> + This feature makes the host keyboard indicators (LEDs) match those + of the VM's emulated keyboard when the machine window is active. + It is currently implemented for macOS and Windows hosts. This + feature is enabled by default on supported host OSes. You can + disable this feature by running the following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> GUI/HidLedsSync 0</screen> + + <para> + This is a per-VM setting that is enabled by default. + </para> + + </sect1> + + <sect1 id="usbtrafficcapturing"> + + <title>Capturing USB Traffic for Selected Devices</title> + + <para> + You can capture USB traffic for single USB devices or on the root + hub level, which captures the traffic of all USB devices attached + to the root hub. &product-name; stores the traffic in a format + which is compatible with Wireshark. To capture the traffic of a + specific USB device it must be attached to the VM with + <command>VBoxManage</command> using the following command: + </para> + +<screen>VBoxManage controlvm <replaceable>VM-name</replaceable> usbattach <replaceable>device uuid</replaceable>|<replaceable>address</replaceable> --capturefile <replaceable>filename</replaceable></screen> + + <para> + In order to enable capturing on the root hub use the following + command while the VM is not running: + </para> + +<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/Devices/usb-ehci/0/LUN#0/Config/CaptureFilename <replaceable>filename</replaceable></screen> + + <para> + The command above enables capturing on the root hub attached to + the EHCI controller. To enable it for the OHCI or XHCI controller + replace <literal>usb-ehci</literal> with + <literal>usb-ohci</literal> or <literal>usb-xhci</literal>, + respectively. + </para> + + </sect1> + + <sect1 id="heartbeatservice"> + + <title>Configuring the Heartbeat Service</title> + + <para> + &product-name; ships a simple heartbeat service. Once the Guest + Additions are active, the guest sends frequent heartbeat pings to + the host. If the guest stops sending the heartbeat pings without + properly terminating the service, the VM process will log this + event in the VBox.log file. In the future it might be possible to + configure dedicated actions but for now there is only a warning in + the log file. + </para> + + <para> + There are two parameters to configure. The <emphasis>heartbeat + interval</emphasis> defines the time between two heartbeat pings. + The default value is 2 seconds, that is, the heartbeat service of + the &product-name; Guest Additions will send a heartbeat ping + every two seconds. The value in nanoseconds can be configured like + this: + </para> + +<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/Devices/VMMDev/0/Config/HeartbeatInterval 2000000000</screen> + + <para> + The <emphasis>heartbeat timeout</emphasis> defines the time the + host waits starting from the last heartbeat ping before it defines + the guest as unresponsive. The default value is 2 times the + heartbeat interval (4 seconds) and can be configured as following, + in nanoseconds: + </para> + +<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/Devices/VMMDev/0/Config/HeartbeatTimeout 4000000000</screen> + + <para> + If the heartbeat timeout expires, there will be a log message like + <emphasis>VMMDev: HeartBeatCheckTimer: Guest seems to be + unresponsive. Last heartbeat received 5 seconds ago.</emphasis> If + another heartbeat ping arrives after this warning, there will be a + log message like <emphasis>VMMDev: GuestHeartBeat: Guest is + alive.</emphasis> + </para> + + </sect1> + + <sect1 id="diskencryption"> + + <title>Encryption of Disk Images</title> + + <para> + &product-name; enables you to transparently encrypt the data + stored in hard disk images for the guest. It does not depend on a + specific image format to be used. Images which have the data + encrypted are not portable between &product-name; and other + virtualization software. + </para> + + <para> + &product-name; uses the AES algorithm in XTS mode and supports + 128-bit or 256-bit data encryption keys (DEK). The DEK is stored + encrypted in the medium properties and is decrypted during VM + startup by entering a password which was chosen when the image was + encrypted. + </para> + + <para> + Since the DEK is stored as part of the VM configuration file, it + is important that it is kept safe. Losing the DEK means that the + data stored in the disk images is lost irrecoverably. Having + complete and up to date backups of all data related to the VM is + the responsibility of the user. + </para> + + <sect2 id="diskencryption-limitations"> + + <title>Limitations of Disk Encryption</title> + + <para> + There are some limitations the user needs to be aware of when + using this feature: + </para> + + <itemizedlist> + + <listitem> + <para> + This feature is part of the &product-name; Extension Pack, + which needs to be installed. Otherwise disk encryption is + unavailable. + </para> + </listitem> + + <listitem> + <para> + Since encryption works only on the stored user data, it is + currently not possible to check for metadata integrity of + the disk image. Attackers might destroy data by removing or + changing blocks of data in the image or change metadata + items such as the disk size. + </para> + </listitem> + + <listitem> + <para> + Exporting appliances which contain encrypted disk images is + not possible because the OVF specification does not support + this. All images are therefore decrypted during export. + </para> + </listitem> + + <listitem> + <para> + The DEK is kept in memory while the VM is running to be able + to decrypt data read and encrypt data written by the guest. + While this should be obvious the user needs to be aware of + this because an attacker might be able to extract the key on + a compromised host and decrypt the data. + </para> + </listitem> + + <listitem> + <para> + When encrypting or decrypting the images, the password is + passed in clear text using the &product-name; API. This + needs to be kept in mind, especially when using third party + API clients which make use of the webservice where the + password might be transmitted over the network. The use of + HTTPS is mandatory in such a case. + </para> + </listitem> + + <listitem> + <para> + Encrypting images with differencing images is only possible + if there are no snapshots or a linear chain of snapshots. + This limitation may be addressed in a future &product-name; + version. + </para> + </listitem> + + <listitem> + <para> + The disk encryption feature can protect the content of the + disks configured for a VM only. It does not cover any other + data related to a VM, including saved state or the + configuration file itself. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="diskencryption-encryption"> + + <title>Encrypting Disk Images</title> + + <para> + Encrypting disk images can be done either using &vbox-mgr; or + the <command>VBoxManage</command>. While &vbox-mgr; is easier to + use, it works on a per VM basis and encrypts all disk images + attached to the specific VM. With <command>VBoxManage</command> + one can encrypt individual images, including all differencing + images. To encrypt an unencrypted medium with + <command>VBoxManage</command>, use: + </para> + +<screen>VBoxManage encryptmedium <replaceable>uuid</replaceable>|<replaceable>filename</replaceable> \ +--newpassword <replaceable>filename</replaceable>|- --cipher <replaceable>cipher-ID</replaceable> --newpasswordid "<replaceable>ID</replaceable></screen> + + <para> + To supply the encryption password point + <command>VBoxManage</command> to the file where the password is + stored or specify <option>-</option> to let VBoxManage ask you + for the password on the command line. + </para> + + <para> + The cipher parameter specifies the cipher to use for encryption + and can be either <literal>AES-XTS128-PLAIN64</literal> or + <literal>AES-XTS256-PLAIN64</literal>. The specified password + identifier can be freely chosen by the user and is used for + correct identification when supplying multiple passwords during + VM startup. + </para> + + <para> + If the user uses the same password when encrypting multiple + images and also the same password identifier, the user needs to + supply the password only once during VM startup. + </para> + + </sect2> + + <sect2 id="diskencryption-startvm"> + + <title>Starting a VM with Encrypted Images</title> + + <para> + When a VM is started using &vbox-mgr;, a dialog will open where + the user needs to enter all passwords for all encrypted images + attached to the VM. If another frontend like VBoxHeadless is + used, the VM will be paused as soon as the guest tries to access + an encrypted disk. The user needs to provide the passwords + through <command>VBoxManage</command> using the following + command: + </para> + +<screen>VBoxManage controlvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> addencpassword <replaceable>ID</replaceable> <replaceable>password</replaceable> [--removeonsuspend yes|no]</screen> + + <para> + <replaceable>ID</replaceable> must be the same as the password + identifier supplied when encrypting the images. + <replaceable>password</replaceable> is the password used when + encrypting the images. Optionally, you can specify + <option>--removeonsuspend yes|no</option> to specify whether to + remove the password from VM memory when the VM is suspended. + Before the VM can be resumed, the user needs to supply the + passwords again. This is useful when a VM is suspended by a host + suspend event and the user does not want the password to remain + in memory. + </para> + + </sect2> + + <sect2 id="diskencryption-decryption"> + + <title>Decrypting Encrypted Images</title> + + <para> + In some circumstances it might be required to decrypt previously + encrypted images. This can be done in &vbox-mgr; for a complete + VM or using <command>VBoxManage</command> with the following + command: + </para> + +<screen>VBoxManage encryptmedium <replaceable>uuid</replaceable>|<replaceable>filename</replaceable> --oldpassword <replaceable>file</replaceable>|-</screen> + + <para> + The only required parameter is the password the image was + encrypted with. The options are the same as for encrypting + images. + </para> + + </sect2> + + </sect1> + + <sect1 id="gimdebug"> + + <title>Paravirtualized Debugging</title> + + <para> + This section covers debugging of guest operating systems using + interfaces supported by paravirtualization providers. + </para> + + <note> + <para> + Paravirtualized debugging significantly alter guest operating + system behaviour and should only be used by expert users for + debugging and diagnostics. + </para> + </note> + + <para> + These debug options are specified as a string of key-value pairs + separated by commas. An empty string disables paravirtualized + debugging. + </para> + + <sect2 id="gimdebughyperv"> + + <title>Hyper-V Debug Options</title> + + <para> + All of the options listed below are optional, and thus the + default value specified will be used when the corresponding + key-value pair is not specified. + </para> + + <itemizedlist> + + <listitem> + <para> + Key: + <emphasis role="bold"><literal>enabled</literal></emphasis> + </para> + + <para> + Value: <literal>0</literal> or <literal>1</literal> + </para> + + <para> + Default: <literal>0</literal> + </para> + + <para> + Specify <literal>1</literal> to enable the Hyper-V debug + interface. If this key-value pair is not specified or the + value is not <literal>1</literal>, the Hyper-V debug + interface is disabled regardless of other key-value pairs + being present. + </para> + </listitem> + + <listitem> + <para> + Key: + <emphasis role="bold"><literal>address</literal></emphasis> + </para> + + <para> + Value: IPv4 address + </para> + + <para> + Default: 127.0.0.1 + </para> + + <para> + Specify the IPv4 address where the remote debugger is + connected. + </para> + </listitem> + + <listitem> + <para> + Key: + <emphasis role="bold"><literal>port</literal></emphasis> + </para> + + <para> + Value: UDP port number + </para> + + <para> + Default: 50000 + </para> + + <para> + Specify the UDP port number where the remote debugger is + connected. + </para> + </listitem> + + <listitem> + <para> + Key: + <emphasis role="bold"><literal>vendor</literal></emphasis> + </para> + + <para> + Value: Hyper-V vendor signature reported by CPUID to the + guest + </para> + + <para> + Default: When debugging is enabled: <literal>Microsoft + Hv</literal>, otherwise: <literal>VBoxVBoxVBox</literal> + </para> + + <para> + Specify the Hyper-V vendor signature which is exposed to the + guest by CPUID. For debugging Microsoft Windows guests, it + is required the hypervisor reports the Microsoft vendor. + </para> + </listitem> + + <listitem> + <para> + Key: + <emphasis role="bold"><literal>hypercallinterface</literal> + </emphasis> + </para> + + <para> + Value: <literal>0</literal> or <literal>1</literal> + </para> + + <para> + Default: <literal>0</literal> + </para> + + <para> + Specify whether hypercalls should be suggested for + initiating debug data transfers between host and guest + rather than MSRs when requested by the guest. + </para> + </listitem> + + <listitem> + <para> + Key: <emphasis role="bold"><literal>vsinterface</literal> + </emphasis> + </para> + + <para> + Value: <literal>0</literal> or <literal>1</literal> + </para> + + <para> + Default: When debugging is enabled, <literal>1</literal>, + otherwise <literal>0</literal> + </para> + + <para> + Specify whether to expose the VS#1 virtualization service + interface to the guest. This interface is required for + debugging Microsoft Windows 10 32-bit guests, but is + optional for other Windows versions. + </para> + </listitem> + + </itemizedlist> + + <sect3 id="gimdebughyperv-windows-setup"> + + <title>Setting up Windows Guests for Debugging with the Hyper-V + Paravirtualization Provider</title> + + <para> + Windows supports debugging over a serial cable, USB, IEEE 1394 + Firewire, and Ethernet. USB and IEEE 1394 are not applicable + for virtual machines, and Ethernet requires Windows 8 or + later. While a serial connection is universally usable, it is + slow. + </para> + + <para> + Debugging using the Hyper-V debug transport, supported on + Windows Vista and later, offers significant benefits. It + provides excellent performance due to direct host-to-guest + transfers, it is easy to set up and requires minimal support + from the hypervisor. It can be used with the debugger running + on the same host as the VM or with the debugger and VM on + separate machines connected over a network. + </para> + + <para> + <emphasis role="bold">Prerequisites</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + A VM configured for Hyper-V paravirtualization running a + Windows Vista or newer Windows guest. You can check the + effective paravirtualization provider for your VM with the + output of the following <command>VBoxManage</command> + command: + </para> + +<screen>$ VBoxManage showvminfo <replaceable>VM-name</replaceable></screen> + </listitem> + + <listitem> + <para> + A sufficiently up-to-date version of the Microsoft WinDbg + debugger required to debug the version of Windows in your + VM. + </para> + </listitem> + + <listitem> + <para> + While Windows 8 and newer Windows guests ship with Hyper-V + debug support, Windows 7 and Vista do not. To use Hyper-V + debugging with a Windows 7 or Vista guest, copy the file + <filename>kdvm.dll</filename> from a Windows 8.0 + installation. This file is typically located in + <filename>C:\Windows\System32</filename>. Copy it to the + same location in your Windows 7/Vista guest. Make sure you + copy the 32-bit or 64-bit version of the DLL which matches + your guest OS. + </para> + + <note> + <para> + Only Windows 8.0 ships <filename>kdvm.dll</filename>. + Windows 8.1 and newer Windows versions do not. + </para> + </note> + </listitem> + + </itemizedlist> + + <para> + <emphasis role="bold">VM and Guest Configuration</emphasis> + </para> + + <orderedlist> + + <listitem> + <para> + Power off the VM. + </para> + </listitem> + + <listitem> + <para> + Enable the debug options with the following + <command>VBoxManage</command> command: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --paravirt-debug "enabled=1"</screen> + + <para> + The above command assumes your debugger will connect to + your host machine on UDP port 50000. However, if you need + to run the debugger on a remote machine you may specify + the remote address and port here. For example: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> \ +--paravirt-debug "enabled=1,address=192.168.32.1,port=55000"</screen> + + <para> + See <xref linkend="gimdebughyperv" /> for the complete set + of options. + </para> + </listitem> + + <listitem> + <para> + Start the VM. + </para> + </listitem> + + <listitem> + <para> + In the guest, start an elevated command prompt and execute + the following commands: + </para> + + <itemizedlist> + + <listitem> + <para> + For a Windows 8 or newer Windows guest: + </para> + +<screen>bcdedit /dbgsettings net hostip:5.5.5.5 port:50000 key:1.2.3.4</screen> + </listitem> + + <listitem> + <para> + For a Windows 7 or Vista guest: + </para> + +<screen>bcdedit /set loadoptions host_ip=5.5.5.5,host_port=50000,encryption_key=1.2.3.4</screen> + +<screen>bcdedit /set dbgtransport kdvm.dll</screen> + + <para> + The IP address and port in the + <command>bcdedit</command> command are ignored when + using the Hyper-V debug transport. Any valid IP and a + port number greater than 49151 and lower than 65536 + can be entered. + </para> + + <para> + The encryption key in the <command>bcdedit</command> + command is relevant and must be valid. The key + "1.2.3.4" used in the above example is valid and may + be used if security is not a concern. If you do not + specify any encryption key, <command>bcdedit</command> + will generate one for you and you will need to copy + this key to later enter in Microsoft WinDbg on the + remote end. This encryption key is used to encrypt the + debug data exchanged between Windows and the debugger. + </para> + </listitem> + + <listitem> + <para> + Run one or more of the following commands to enable + debugging for the appropriate phase or component of + your Windows guest: + </para> + +<screen>bcdedit /set debug on</screen> + +<screen>bcdedit /set bootdebug on</screen> + +<screen>bcdedit /set {bootmgr} bootdebug on</screen> + + <para> + Please note that the <command>bootdebug</command> + options are only effective on Windows 8 or newer when + using the Hyper-V debug transport. Refer to Microsoft + Windows documentation for detailed explanation of + <command>bcdedit</command> options. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Start Microsoft WinDbg on your host machine or remote + host. + </para> + + <para> + From the <emphasis role="bold">File</emphasis> menu, + select <emphasis role="bold">Kernel Debug</emphasis>. On + the <emphasis role="bold">NET</emphasis> tab, specify the + UDP port number you used in the + <literal>paravirtdebug</literal> options. If you did not + specify any, leave it as 50000. Ensure that the UDP port + is not blocked by a firewall or other security software. + </para> + + <para> + In the <emphasis role="bold">Key</emphasis> field, enter + <literal>1.2.3.4</literal> or the encryption key from the + <command>bcdedit</command> command in your Windows guest. + </para> + + <para> + Click <emphasis role="bold">OK</emphasis> to start + listening for connections. Microsoft WinDbg typically + shows a Waiting to Reconnect message during this phase. + </para> + + <para> + Alternatively, to directly start a debug session, run + WinDbg from the command line as follows : + </para> + +<screen>windbg.exe -k net:port=50000,key=1.2.3.4</screen> + + <para> + See the WinDbg documentation for the complete command line + syntax. + </para> + </listitem> + + <listitem> + <para> + Reboot your Windows guest and it should then connect as a + debuggee with Microsoft WinDbg. + </para> + </listitem> + + </orderedlist> + + </sect3> + + </sect2> + + </sect1> + + <sect1 id="pcspeaker_passthrough"> + + <title>PC Speaker Passthrough</title> + + <para> + As an experimental feature, primarily due to being limited to + Linux host only and unknown Linux distribution coverage, + &product-name; supports passing through the PC speaker to the + host. The PC speaker, sometimes called the system speaker, is a + way to produce audible feedback such as beeps without the need for + regular audio and sound card support. + </para> + + <para> + The PC speaker passthrough feature in &product-name; handles beeps + only. Advanced PC speaker use by the VM, such as PCM audio, will + not work, resulting in undefined host behavior. + </para> + + <para> + Producing beeps on Linux is a very complex topic. &product-name; + offers a collection of options, in an attempt to make this work + deterministically and reliably on as many Linux distributions and + system configurations as possible. These are summarized in the + following table. + </para> + + <table id="table-pcspeaker-config" tabstyle="oracle-all"> + <title>PC Speaker Configuration Options</title> + <tgroup cols="3"> + <thead> + <row> + <entry><para> + <emphasis role="bold">Code</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Device</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Notes</emphasis> + </para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para> + 1 + </para></entry> + <entry><para> + <filename>/dev/input/by-path/platform-pcspkr-event-spkr</filename> + </para></entry> + <entry><para> + Direct host PC speaker use. + </para></entry> + </row> + <row> + <entry><para> + 2 + </para></entry> + <entry><filename>/dev/tty</filename></entry> + <entry><para> + Uses the terminal association of the VM process. VM + needs to be started on a virtual console. + </para></entry> + </row> + <row> + <entry><para> + 3 + </para></entry> + <entry><para> + <filename>/dev/tty0</filename> or + <filename>/dev/vc/0</filename> + </para></entry> + <entry><para> + Can only be used by user <literal>root</literal> or + users with <literal>cap_sys_tty_config</literal> + capability. + </para></entry> + </row> + <row> + <entry><para> + 9 + </para></entry> + <entry><para> + A user-specified console or evdev device path. + </para></entry> + <entry><para> + As for codes 1 to 3, but with a custom device path. + </para></entry> + </row> + <row> + <entry><para> + 70 + </para></entry> + <entry><para> + <filename>/dev/tty</filename> + </para></entry> + <entry><para> + Standard beep only. Loses frequency and length. See code + 2. + </para></entry> + </row> + <row> + <entry><para> + 79 + </para></entry> + <entry><para> + A user-specified terminal device path. + </para></entry> + <entry><para> + As for code 70, but with a custom device path. + </para></entry> + </row> + <row> + <entry><para> + 100 + </para></entry> + <entry><para> + All of the above. + </para></entry> + <entry><para> + Tries all the available codes. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + To enable PC speaker passthrough use the following command: + </para> + +<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal/Devices/i8254/0/Config/PassthroughSpeaker" <replaceable>N</replaceable></screen> + + <para> + Replace <replaceable>N</replaceable> with the code representing + the case you want to use. Changing this setting takes effect when + you next start the VM. It is safe to enable PC speaker passthrough + on all host OSes. It will only have an effect on Linux. + </para> + + <para> + The VM log file, <filename>VBox.log</filename>, contains lines + with the prefix <literal>PIT: speaker:</literal> showing the PC + speaker passthrough setup activities. It gives hints which device + it picked or why it failed. + </para> + + <para> + Enabling PC speaker passthrough for the VM is usually the simple + part. The real difficulty is making sure that &product-name; can + access the necessary device, because in a typical Linux install + most of them can only be accessed by user <literal>root</literal>. + You should follow the preferred way to persistently change this, + such as by referring to your distribution's documentation. Since + there are countless Linux distribution variants, we can only give + the general hints that there is often a way to give the X11 + session user access to additional devices, or you need to find a + working solution using a udev configuration file. If everything + fails you might try setting the permissions using a script which + is run late enough in the host system startup. + </para> + + <para> + Sometimes additional rules are applied by the kernel to limit + access. For example, that the VM process must have the same + controlling terminal as the device configured to be used for + beeping, something which is often very difficult to achieve for + GUI applications such as &product-name;. The table above contains + some hints, but in general refer to the Linux documentation. + </para> + + <para> + If you have trouble getting any beeps even if the device + permissions are set up and VBox.log confirms that it uses evdev or + console for the PC speaker control, check if your system has a PC + speaker. Some systems do not have one. Other complications can + arise from Linux rerouting the PC speaker output to a sound card. + Check if the beeps are audible if you connect speakers to your + sound card. Today almost all systems have one. Finally, check if + the audio mixer control has a channel named "beep", which could be + hidden in the mixer settings, and that it is not muted. + </para> + + </sect1> + + <sect1 id="usbip"> + + <title>Accessing USB devices Exposed Over the Network with USB/IP</title> + + <para> + &product-name; supports passing through USB devices which are + exposed over the network using the USB over IP protocol without + the need to configure the client side provided by the kernel and + usbip tools. Furthermore, this feature works with &product-name; + running on any supported host, rather than just Linux alone, as is + the case with the official client. + </para> + + <para> + To enable support for passing through USB/IP devices, use the + following command to add the device server that exports the + devices: + </para> + +<screen>VBoxManage usbdevsource add <replaceable>unique-name</replaceable> --backend <replaceable>USBIP</replaceable> --address <replaceable>device-server</replaceable>[:<replaceable>port</replaceable>]</screen> + + <para> + USB devices exported on the device server are then accessible + through &vbox-mgr; or <command>VBoxManage</command>, like any USB + devices attached locally. This can be used multiple times to + access different device servers. + </para> + + <para> + To remove a device server, the following command can be used: + </para> + +<screen>$ VBoxManage usbdevsource remove <replaceable>unique-name</replaceable></screen> + + <sect2 id="usbip-setup-server"> + + <title>Setting up USB/IP Support on a Linux System</title> + + <para> + This section gives a brief overview on how to set up a Linux + based system to act as a USB device server. The system on the + server requires that the <filename>usbip-core.ko</filename> and + <filename>usbip-host.ko</filename> kernel drivers are available, + and that the USB/IP tools package is installed. The particular + installation method for the necessary tools depends on which + distribution is used. For example, for Debian based systems, use + the following command to install the required tools: + </para> + +<screen>$ apt-get install usbip-utils</screen> + + <para> + To check whether the necessary tools are already installed use + the following command: + </para> + +<screen> +$ usbip list -l + </screen> + + <para> + This should produce output similar to that shown in the example + below: + </para> + +<screen> + - busid 4-2 (0bda:0301) + Realtek Semiconductor Corp. : multicard reader (0bda:0301) + + - busid 5-1 (046d:c52b) + Logitech, Inc. : Unifying Receiver (046d:c52b) + </screen> + + <para> + If everything is installed, the USB/IP server needs to be + started as <literal>root</literal> using the following command: + </para> + +<screen># usbipd -D</screen> + + <para> + See the documentation for the installed distribution to + determine how to start the service when the system boots. + </para> + + <para> + By default, no device on the server is exported. This must be + done manually for each device. To export a device use the + following command: + </para> + +<screen># usbip bind -b "bus identifier"</screen> + + <para> + To export the multicard reader in the previous example: + </para> + +<screen># usbip bind -b 4-2</screen> + + </sect2> + + <sect2 id="usbip-security"> + + <title>Security Considerations</title> + + <para> + The communication between the server and client is unencrypted + and there is no authorization required to access exported + devices. An attacker might sniff sensitive data or gain control + over a device. To mitigate this risk, the device should be + exposed over a local network to which only trusted clients have + access. To access the device remotely over a public network, a + VPN solution should be used to provide the required level of + security protection. + </para> + + </sect2> + + </sect1> + + <sect1 id="hyperv-support"> + + <title>Using Hyper-V with &product-name;</title> + + <para> + &product-name; can be used on a Windows host where Hyper-V is + running. This is an experimental feature. + </para> + + <para> + No configuration is required. &product-name; detects Hyper-V + automatically and uses Hyper-V as the virtualization engine for + the host system. The CPU icon in the VM window status bar + indicates that Hyper-V is being used. + </para> + + <note> + <para> + When using this feature, some host systems might experience + significant &product-name; performance degradation. + </para> + </note> + + </sect1> + + <sect1 id="nested-virt"> + + <title>Nested Virtualization</title> + + <para> + &product-name; supports <emphasis>nested + virtualization</emphasis>. This feature enables the passthrough of + hardware virtualization functions to the guest VM. That means that + you can install a hypervisor, such as &product-name;, Oracle VM + Server or KVM, on an &product-name; guest. You can then create and + run VMs within the guest VM. + </para> + + <para> + Hardware virtualization features not present on the host CPU will + not be exposed to the guest. In addition, some features such as + nested paging are not yet supported for passthrough to the guest. + </para> + + <para> + You can enable the nested virtualization feature in one of the + following ways: + </para> + + <itemizedlist> + + <listitem> + <para> + From &vbox-mgr;, select the <emphasis role="bold">Enable + Nested VT-x/AMD-V</emphasis> check box on the + <emphasis role="bold">Processor</emphasis> tab. To disable the + feature, deselect the check box. + </para> + </listitem> + + <listitem> + <para> + Use the <option>--nested-hw-virt</option> option of the + <command>VBoxManage modifyvm</command> command to enable or + disable nested virtualization. See + <xref linkend="vboxmanage-modifyvm"/>. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="vboxsvc-session-0"> + + <title>VBoxSVC running in Windows Session 0</title> + + <para> + &product-name; supports executing the VBoxSVC in Windows session + 0. This allows VBoxSVC to run like a regular Windows service, + which in turn enables headless VMs to continue running even if the + user logs out. + + <note> + <para> + This is currently an experimental feature. + </para> + </note> + </para> + + <para> + The feature is disabled by default and can be enabled by creating + a REG_DWORD value <literal>ServerSession0</literal> in the key + <literal>HKEY_LOCAL_MACHINE\Software\Oracle\VirtualBox\VBoxSDS</literal> + of the Windows registry. Specify <literal>1</literal> as the + value's data to enable the feature, or <literal>0</literal> to + disable the feature. A host reboot is needed in order to make the + change effective. + </para> + + <sect2 id="vboxsvc-session-0-known-issues"> + + <title>Known Issues</title> + + <itemizedlist> + + <listitem> + <para> + Due to different Windows sessions having their own set of + resources, there might be some issues with accessing network + shares created in the interactive user session when at least + one of the &product-name; processes are running in session + 0. + </para> + + <para> + For accessing network shares within session 0, a possible + workaround is to establish permanent access to the share and + then restart the host. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + </sect1> + + <xi:include href="user_isomakercmd-man.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + +</chapter> diff --git a/doc/manual/en_US/user_BasicConcepts.xml b/doc/manual/en_US/user_BasicConcepts.xml new file mode 100644 index 00000000..285072e2 --- /dev/null +++ b/doc/manual/en_US/user_BasicConcepts.xml @@ -0,0 +1,3052 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="BasicConcepts"> + + <title>Configuring Virtual Machines</title> + + <para> + This chapter provides detailed steps for configuring an + &product-name; virtual machine (VM). For an introduction to + &product-name; and steps to get your first virtual machine running, + see <xref linkend="Introduction" />. + </para> + + <para> + You have considerable latitude when deciding what virtual hardware + to provide to the guest. Use virtual hardware to communicate with + the host system or with other guests. For example, you can use + virtual hardware in the following ways: + </para> + + <itemizedlist> + + <listitem> + <para> + Have &product-name; present an ISO CD-ROM image to a guest + system as if it were a physical CD-ROM. + </para> + </listitem> + + <listitem> + <para> + Provide a guest system access to the physical network through + its virtual network card. + </para> + </listitem> + + <listitem> + <para> + Provide the host system, other guests, and computers on the + Internet access to the guest system. + </para> + </listitem> + + </itemizedlist> + + <sect1 id="guestossupport"> + + <title>Supported Guest Operating Systems</title> + + <para> + Because &product-name; is designed to provide a generic + virtualization environment for x86 systems, it can run guest + operating systems (OSes) of any kind. + </para> + + <para> + The following guest OS platforms are supported: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Platforms With Full Support.</emphasis> + These guest OS platforms qualify for Oracle Premier Support. + See <xref linkend="table-premier-support"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Platforms With Limited + Support.</emphasis> These legacy guest OS platforms can be + used with &product-name;, but only qualify for <emphasis>best + effort</emphasis> support. Therefore, resolution of customer + issues is not guaranteed. See + <xref linkend="table-limited-support"/>. + </para> + </listitem> + + </itemizedlist> + + <table id="table-premier-support" tabstyle="oracle-all"> + <title>Guest Operating Systems With Full Support</title> + <tgroup cols="2"> + <thead> + <row> + <entry><para> + <emphasis role="bold">Operating System</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Comments</emphasis> + </para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para> + Windows 11 (64-bit) + </para></entry> + <entry><para> + Insider preview builds are not supported + </para></entry> + </row> + <row> + <entry><para> + Windows 10 (32-bit and 64-bit) + </para></entry> + <entry><para> + Insider preview builds are not supported + </para></entry> + </row> + <row> + <entry><para> + Windows 8 and 8.1 (32-bit and 64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Windows Server 2019 (64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Windows Server 2016 (64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Windows Server 2012 and 2012 R2 (64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Solaris 11 (32-bit and 64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Solaris 10 8/11 Update 10 and later (32-bit and 64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Oracle Linux 8 (64-bit) + </para></entry> + <entry><para> + Includes Red Hat Enterprise Linux 8, CentOS 8 + </para></entry> + </row> + <row> + <entry><para> + Oracle Linux 7 (64-bit) + </para></entry> + <entry><para> + Includes Red Hat Enterprise Linux 7, CentOS 7 + </para></entry> + </row> + <row> + <entry><para> + Oracle Linux 6 (32-bit and 64-bit) + </para></entry> + <entry><para> + Includes Red Hat Enterprise Linux 6, CentOS 6 + </para></entry> + </row> + <row> + <entry><para> + Ubuntu 16.04 LTS (Xenial Xerus) (32-bit and 64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Ubuntu 18.04 LTS (Bionic Beaver) (64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Ubuntu 20.04 LTS (Focal Fossa) (64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + SUSE Linux Enterprise Server 15 (64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + SUSE Linux Enterprise Server 12 (64-bit) + </para></entry> + <entry><para></para></entry> + </row> + </tbody> + </tgroup> + </table> + + <table id="table-limited-support" tabstyle="oracle-all"> + <title>Legacy Guest Operating Systems With Limited Support</title> + <tgroup cols="2"> + <thead> + <row> + <entry><para> + <emphasis role="bold">Operating System</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Comments</emphasis> + </para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para> + Windows 7 (32-bit and 64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Windows Vista SP2 and later (32-bit and 64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Windows XP (32-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Windows Vista (32-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Windows Server 2008 and 2008 R2 (32-bit and 64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Windows Server 2003 (32-bit and 64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Oracle Linux 5 (32-bit and 64-bit) + </para></entry> + <entry><para> + Includes Red Hat Enterprise Linux 5, CentOS 5 + </para></entry> + </row> + <row> + <entry><para> + Ubuntu 14.04.5 LTS (Trusty Tahr) (32-bit and 64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + OS/2 Warp 4.5 + </para></entry> + <entry><para></para></entry> + </row> + </tbody> + </tgroup> + </table> + + <sect2 id="intro-macosxguests"> + + <title>Mac OS X Guests</title> + + <para> + &product-name; enables you to install and execute unmodified + versions of Mac OS X guests on supported host hardware. Note + that this feature is experimental and thus unsupported. + </para> + + <para> + &product-name; is the first product to provide the modern PC + architecture expected by OS X without requiring any of the + modifications used by competing virtualization solutions. For + example, some competing solutions perform modifications to the + Mac OS X install DVDs, such as a different boot loader and + replaced files. + </para> + + <para> + Be aware of the following important issues before you attempt to + install a Mac OS X guest: + </para> + + <itemizedlist> + + <listitem> + <para> + Mac OS X is commercial, licensed software and contains + <emphasis role="bold">both license and technical + restrictions</emphasis> that limit its use to certain + hardware and usage scenarios. You must understand and comply + with these restrictions. + </para> + + <para> + In particular, Apple prohibits the installation of most + versions of Mac OS X on non-Apple hardware. + </para> + + <para> + These license restrictions are also enforced on a technical + level. Mac OS X verifies that it is running on Apple + hardware. Most DVDs that accompany Apple hardware check for + the exact model. These restrictions are + <emphasis>not</emphasis> circumvented by &product-name; and + continue to apply. + </para> + </listitem> + + <listitem> + <para> + Only <emphasis role="bold">CPUs</emphasis> that are known + and tested by Apple are supported. As a result, if your + Intel CPU is newer than the Mac OS X build, or if you have a + non-Intel CPU, you will likely encounter a panic during + bootup with an "Unsupported CPU" exception. + </para> + + <para> + Ensure that you use the Mac OS X DVD that comes with your + Apple hardware. + </para> + </listitem> + + <listitem> + <para> + The Mac OS X installer expects the hard disk to be + <emphasis>partitioned</emphasis>. So, the installer will not + offer a partition selection to you. Before you can install + the software successfully, start the Disk Utility from the + Tools menu and partition the hard disk. Close the Disk + Utility and proceed with the installation. + </para> + </listitem> + + <listitem> + <para> + In addition, Mac OS X support in &product-name; is an + experimental feature. See <xref linkend="KnownIssues" />. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="intro-64bitguests"> + + <title>64-bit Guests</title> + + <warning> + <para> + Be sure to enable <emphasis role="bold">I/O APIC</emphasis> + for virtual machines that you intend to use in 64-bit mode. + This is especially true for 64-bit Windows VMs. See + <xref linkend="settings-motherboard" />. For 64-bit Windows + guests, ensure that the VM uses the + <emphasis role="bold">Intel networking device</emphasis> + because there is no 64-bit driver support for the AMD PCNet + card. See <xref linkend="nichardware" />. + </para> + </warning> + + <para> + If you use the <emphasis role="bold">Create VM</emphasis> wizard + of &vbox-mgr;, &product-name; automatically uses the correct + settings for each selected 64-bit OS type. See + <xref linkend="create-vm-wizard" />. + </para> + + </sect2> + + </sect1> + + <sect1 id="basic-unattended"> + + <title>Unattended Guest Installation</title> + + <para> + &product-name; can install a guest OS automatically. You only need + to provide the installation medium and a few other parameters, + such as the name of the default user. + </para> + + <para> + You can perform an unattended guest installation in the following + ways: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Use the Create Virtual Machine + wizard.</emphasis> An optional step in the wizard enables you + to configure unattended installation. You can specify the + default user credentials for the guest OS and also whether to + install the Guest Additions automatically. See + <xref linkend="create-vm-wizard"/>. + </para> + + <para> + During this step, &product-name; scans the installation medium + and changes certain parameters to ensure a seamless + installation as a guest running on &product-name;. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Use the <command>VBoxManage</command> + commands.</emphasis> + <xref linkend="unattended-guest-install-example"/> describes + how to perform an unattended guest installation for an Oracle + Linux guest. + </para> + </listitem> + + </itemizedlist> + + <para> + When you first start a VM that has been configured for unattended + installation, the guest OS installation is performed + automatically. + </para> + + <para> + The installation operation changes the boot device order to boot + the virtual hard disk first and then the virtual DVD drive. If the + virtual hard disk is empty prior to the automatic installation, + the VM boots from the virtual DVD drive and begins the + installation. + </para> + + <para> + If the virtual hard disk contains a bootable OS, the installation + operation exits. In this case, change the boot device order + manually by pressing F12 during the BIOS splash screen. + </para> + + <sect2 id="unattended-guest-install-example"> + + <title>Using VBoxManage Commands for Unattended Guest Installation</title> + + <para> + The following example shows how to perform an unattended guest + installation for an Oracle Linux VM. The example uses various + <command>VBoxManage</command> commands to prepare the guest VM. + The <command>VBoxManage unattended install</command> command is + then used to install and configure the guest OS. + </para> + + <orderedlist> + + <listitem> + <para> + Create the virtual machine. + </para> + +<screen># VM="ol7-autoinstall" +# VBoxManage list ostypes +# VBoxManage createvm --name $VM --ostype "Oracle_64" --register</screen> + + <para> + Note the following: + </para> + + <itemizedlist> + + <listitem> + <para> + The $VM variable represents the name of the VM. + </para> + </listitem> + + <listitem> + <para> + The <command>VBoxManage list ostypes</command> command + lists the guest OSes supported by &product-name;, + including the name used for each OS in the + <command>VBoxManage</command> commands. + </para> + </listitem> + + <listitem> + <para> + A 64-bit Oracle Linux 7 VM is created and registered + with &product-name;. + </para> + </listitem> + + <listitem> + <para> + The VM has a unique UUID. + </para> + </listitem> + + <listitem> + <para> + An XML settings file is generated. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Create a virtual hard disk and storage devices for the VM. + </para> + +<screen># VBoxManage createhd --filename /VirtualBox/$VM/$VM.vdi --size 32768 +# VBoxManage storagectl $VM --name "SATA Controller" --add sata --controller IntelAHCI +# VBoxManage storageattach $VM --storagectl "SATA Controller" --port 0 --device 0 \ +--type hdd --medium /VirtualBox/$VM/$VM.vdi +# VBoxManage storagectl $VM --name "IDE Controller" --add ide +# VBoxManage storageattach $VM --storagectl "IDE Controller" --port 0 --device 0 \ +--type dvddrive --medium /u01/Software/OL/OracleLinux-R7-U6-Server-x86_64-dvd.iso</screen> + + <para> + The previous commands do the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Create a 32768 MB virtual hard disk. + </para> + </listitem> + + <listitem> + <para> + Create a SATA storage controller and attach the virtual + hard disk. + </para> + </listitem> + + <listitem> + <para> + Create an IDE storage controller for a virtual DVD drive + and attach an Oracle Linux installation ISO. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + (Optional) Configure some settings for the VM. + </para> + +<screen># VBoxManage modifyvm $VM --ioapic on +# VBoxManage modifyvm $VM --boot1 dvd --boot2 disk --boot3 none --boot4 none +# VBoxManage modifyvm $VM --memory 8192 --vram 128</screen> + + <para> + The previous commands do the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Enable I/O APIC for the motherboard of the VM. + </para> + </listitem> + + <listitem> + <para> + Configure the boot device order for the VM. + </para> + </listitem> + + <listitem> + <para> + Allocate 8192 MB of RAM and 128 MB of video RAM to the + VM. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Perform an unattended install of the OS. + </para> + +<screen># VBoxManage unattended install $VM \ +--iso=/u01/Software/OL/OracleLinux-R7-U6-Server-x86_64-dvd.iso \ +--user=<replaceable>login</replaceable> --full-user-name=<replaceable>name</replaceable> --password <replaceable>password</replaceable> \ +--install-additions --time-zone=CET</screen> + + <para> + The previous command does the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Specifies an Oracle Linux ISO as the installation ISO. + </para> + </listitem> + + <listitem> + <para> + Specifies a login name, full name, and login password + for a default user on the guest OS. + </para> + + <para> + Note that the specified password is also used for the + root user account on the guest. + </para> + </listitem> + + <listitem> + <para> + Installs the Guest Additions on the VM. + </para> + </listitem> + + <listitem> + <para> + Sets the time zone for the guest OS to Central European + Time (CET). + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Start the virtual machine. + </para> + + <para> + This step completes the unattended installation process. + </para> + +<screen># VBoxManage startvm $VM --type headless</screen> + + <para> + The VM starts in headless mode, which means that the + &vbox-mgr; window does not open. + </para> + </listitem> + + <listitem> + <para> + (Optional) Update the guest OS to use the latest Oracle + Linux packages. + </para> + + <para> + On the guest VM, run the following command: + </para> + +<screen># yum update</screen> + </listitem> + + </orderedlist> + + </sect2> + + </sect1> + + <sect1 id="emul-hardware"> + + <title>Emulated Hardware</title> + + <para> + &product-name; virtualizes nearly all hardware of the host. + Depending on a VM's configuration, the guest will see the + following virtual hardware: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Input devices.</emphasis> &product-name; + can emulate a standard PS/2 keyboard and mouse. These devices + are supported by most guest OSes. + </para> + + <para> + In addition, &product-name; can provide virtual USB input + devices to avoid having to capture mouse and keyboard, as + described in <xref linkend="keyb_mouse_normal" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Graphics.</emphasis> The default + &product-name; graphics device for Windows guests is an SVGA + device. For Linux guests, the default graphics device emulates + a VMware SVGA graphics device. See + <xref linkend="settings-screen"/>. + </para> + + <para> + For legacy guest OSes, a VGA-compatible graphics device is + available. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Storage.</emphasis> &product-name; + emulates the most common types of hard disk controllers. See + <xref linkend="harddiskcontrollers" />. Whereas supporting + only one of these controllers would be enough for + &product-name; by itself, this multitude of storage adapters + is required for compatibility with other hypervisors. Windows + is very selective about its boot devices, and migrating VMs + between hypervisors is very difficult or impossible if the + storage controllers are different. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Networking.</emphasis> See + <xref linkend="nichardware" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">USB.</emphasis> &product-name; emulates + these types of USB host controllers: xHCI, EHCI, and OHCI. + While xHCI handles all USB transfer speeds, some legacy guest + OSes may not support xHCI. Note that for some legacy Windows + guests, third party drivers must be installed for xHCI + support. + </para> + + <para> + Legacy guest OSes typically support OHCI and EHCI. These two + controllers are needed because OHCI only handles USB low-speed + and full-speed devices (both USB 1.x and 2.0), while EHCI only + handles high-speed devices (USB 2.0 only). + </para> + + <para> + The emulated USB controllers do not communicate directly with + devices on the host. Instead they communicate with a virtual + USB layer which abstracts the USB protocol and enables the use + of remote USB devices. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Audio.</emphasis> See + <xref linkend="settings-audio" />. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="generalsettings"> + + <title>General Settings</title> + + <para> + In the <emphasis role="bold">Settings</emphasis> window, under + <emphasis role="bold">General</emphasis>, you can configure the + most fundamental aspects of the virtual machine such as memory and + essential hardware. The following tabs are available. + </para> + + <sect2 id="settings-basic"> + + <title>Basic Tab</title> + + <para> + In the <emphasis role="bold">Basic</emphasis> tab of the + <emphasis role="bold">General</emphasis> settings category, you + can find these settings: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Name:</emphasis> The name of the the + VM, as shown in the list of VMs in the main VirtualBox + Manager window. Using this name, &product-name; also saves + the VM's configuration files. If you change the name, + &product-name; renames these files as well. As a result, you + can only use characters which are allowed for file names on + your host OS. + </para> + + <para> + Note that internally, &product-name; uses unique identifiers + (UUIDs) to identify virtual machines. You can display these + using the <command>VBoxManage</command> commands. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Type:</emphasis> The type of the guest + OS for the VM. This is the same setting that is specified in + the <emphasis role="bold">New Virtual Machine</emphasis> + wizard. See <xref linkend="create-vm-wizard" />. + </para> + + <para> + Whereas the default settings of a newly created VM depend on + the selected OS type, changing the type later has no effect + on VM settings. This value is purely informational and + decorative. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Version:</emphasis> The version of the + guest OS for the VM. This is the same setting that is + specified in the <emphasis role="bold">New Virtual + Machine</emphasis> wizard. See + <xref linkend="create-vm-wizard" />. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="settings-general-advanced"> + + <title>Advanced Tab</title> + + <para> + The following settings are available in the + <emphasis role="bold">Advanced</emphasis> tab: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Snapshot Folder:</emphasis> By + default, &product-name; saves snapshot data together with + your other &product-name; configuration data. See + <xref linkend="vboxconfigdata" />. With this setting, you + can specify any other folder for each VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Shared Clipboard:</emphasis> You can + select here whether the clipboard of the guest OS should be + shared with that of your host. If you select + <emphasis role="bold">Bidirectional</emphasis>, then + &product-name; will always make sure that both clipboards + contain the same data. If you select + <emphasis role="bold">Host to Guest</emphasis> or + <emphasis role="bold">Guest to Host</emphasis>, then + &product-name; will only ever copy clipboard data in one + direction. + </para> + + <para> + Clipboard sharing requires that the &product-name; Guest + Additions be installed. In such a case, this setting has no + effect. See <xref linkend="guestadditions" />. + </para> + + <para> + For security reasons, the shared clipboard is disabled by + default. This setting can be changed at any time using the + <emphasis role="bold">Shared Clipboard</emphasis> menu item + in the <emphasis role="bold">Devices</emphasis> menu of the + virtual machine. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Drag and Drop:</emphasis> This setting + enables support for drag and drop. Select an object, such as + a file, from the host or guest and directly copy or open it + on the guest or host. Multiple drag and drop modes for a VM + enable restricting of access in either direction. + </para> + + <para> + For drag and drop to work the Guest Additions need to be + installed on the guest. + </para> + + <note> + <para> + Drag and drop is disabled by default. This setting can be + changed at any time using the <emphasis role="bold">Drag + and Drop</emphasis> menu item in the + <emphasis role="bold">Devices</emphasis> menu of the + virtual machine. + </para> + </note> + + <para> + See <xref linkend="guestadd-dnd"/>. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="settings-description"> + + <title>Description Tab</title> + + <para> + On the <emphasis role="bold">Description</emphasis> tab you can + enter a description for your virtual machine. This has no effect + on the functionality of the machine, but you may find this space + useful to note down things such as the configuration of a + virtual machine and the software that has been installed into + it. + </para> + + <para> + To insert a line break into the + <emphasis role="bold">Description</emphasis> text field, press + Shift+Enter. + </para> + + </sect2> + + <sect2 id="settings-disk-encryption"> + + <title>Disk Encryption Tab</title> + + <para> + The <emphasis role="bold">Disk Encryption</emphasis> tab enables + you to encrypt disks that are attached to the virtual machine. + </para> + + <para> + To enable disk encryption, select the + <emphasis role="bold">Enable Disk Encryption</emphasis> check + box. + </para> + + <para> + Settings are available to configure the cipher used for + encryption and the encryption password. + </para> + + <note> + <para> + All files related to the virtual machine except disk images + are stored unencrypted. To encrypt these files, use the + <command>VBoxManage encryptvm</command> command as described + in <xref linkend="vmencryption"/>. + </para> + </note> + + </sect2> + + </sect1> + + <sect1 id="settings-system"> + + <title>System Settings</title> + + <para> + The <emphasis role="bold">System</emphasis> category groups + various settings that are related to the basic hardware that is + presented to the virtual machine. + </para> + + <note> + <para> + As the activation mechanism of Microsoft Windows is sensitive to + hardware changes, if you are changing hardware settings for a + Windows guest, some of these changes may trigger a request for + another activation with Microsoft. + </para> + </note> + + <para> + The following tabs are available. + </para> + + <sect2 id="settings-motherboard"> + + <title>Motherboard Tab</title> + + <para> + On the <emphasis role="bold">Motherboard</emphasis> tab, you can + configure virtual hardware that would normally be on the + motherboard of a real computer. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Base Memory:</emphasis> Sets the + amount of RAM that is allocated and given to the VM when it + is running. The specified amount of memory will be requested + from the host OS, so it must be available or made available + as free memory on the host when attempting to start the VM + and will not be available to the host while the VM is + running. This is the same setting that was specified in the + <emphasis role="bold">New Virtual Machine</emphasis> wizard, + as described in <xref linkend="create-vm-wizard" />. + </para> + + <para> + Generally, it is possible to change the memory size after + installing the guest OS. But you must not reduce the memory + to an amount where the OS would no longer boot. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Boot Order:</emphasis> Determines the + order in which the guest OS will attempt to boot from the + various virtual boot devices. Analogous to a real PC's BIOS + setting, &product-name; can tell a guest OS to start from + the virtual floppy, the virtual CD/DVD drive, the virtual + hard drive (each of these as defined by the other VM + settings), the network, or none of these. + </para> + + <para> + If you select <emphasis role="bold">Network</emphasis>, the + VM will attempt to boot from a network using the PXE + mechanism. This needs to be configured in detail on the + command line. See <xref linkend="vboxmanage-modifyvm" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Chipset:</emphasis> You can select + which chipset will be presented to the virtual machine. + PIIX3 is the default chipset for most guests. For some guest + OSes such as Mac OS X, the PIIX3 chipset is not well + supported. As a result, &product-name; supports an emulation + of the ICH9 chipset, which supports PCI express, three PCI + buses, PCI-to-PCI bridges and Message Signaled Interrupts + (MSI). This enables modern OSes to address more PCI devices + and no longer requires IRQ sharing. Using the ICH9 chipset + it is also possible to configure up to 36 network cards, + compared to a maximum of eight network adapters with PIIX3. + Note that ICH9 support is experimental and not recommended + for guest OSes which do not require it. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">TPM:</emphasis> Enables support for a + Trusted Platform Module (TPM) security processor. Choose + from the supported TPM versions. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Pointing Device:</emphasis> The + default virtual pointing device for some guest OSes is the + traditional PS/2 mouse. If set to <emphasis role="bold">USB + Tablet</emphasis>, &product-name; reports to the virtual + machine that a USB tablet device is present and communicates + mouse events to the virtual machine through this device. + Another setting is <emphasis role="bold">USB Multi-Touch + Tablet</emphasis>, which is suitable for guests running + Windows 8 or later. + </para> + + <para> + Using the virtual USB tablet has the advantage that + movements are reported in absolute coordinates, instead of + as relative position changes. This enables &product-name; to + translate mouse events over the VM window into tablet events + without having to "capture" the mouse in the guest as + described in <xref linkend="keyb_mouse_normal" />. This + makes using the VM less tedious even if Guest Additions are + not installed. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable I/O APIC:</emphasis> Advanced + Programmable Interrupt Controllers (APICs) are an x86 + hardware feature that have replaced Programmable Interrupt + Controllers (PICs). With an I/O APIC, OSes can use more than + 16 interrupt requests (IRQs) and therefore avoid IRQ sharing + for improved reliability. + </para> + + <note> + <para> + Enabling the I/O APIC is <emphasis>required</emphasis>, + especially for 64-bit Windows guest OSes. It is also + required if you want to use more than one virtual CPU in a + virtual machine. + </para> + </note> + + <para> + However, software support for I/O APICs has been unreliable + with some OSes other than Windows. Also, the use of an I/O + APIC slightly increases the overhead of virtualization and + therefore slows down the guest OS a little. + </para> + + <warning> + <para> + All Windows OSes install different kernels, depending on + whether an I/O APIC is available. As with ACPI, the I/O + APIC therefore <emphasis>must not be turned off after + installation</emphasis> of a Windows guest OS. Turning it + on after installation will have no effect however. + </para> + </warning> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Hardware Clock in UTC Time:</emphasis> + If selected, &product-name; will report the system time in + UTC format to the guest instead of the local (host) time. + This affects how the virtual real-time clock (RTC) operates + and may be useful for UNIX-like guest OSes, which typically + expect the hardware clock to be set to UTC. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable EFI:</emphasis> Enables + Extensible Firmware Interface (EFI), which replaces the + legacy BIOS and may be useful for certain advanced use + cases. See <xref linkend="efi" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable Secure Boot:</emphasis> Enables + Secure Boot, to provide a secure environment for starting + the guest OS. + </para> + </listitem> + + </itemizedlist> + + <para> + In addition, you can turn off the <emphasis role="bold">Advanced + Configuration and Power Interface (ACPI)</emphasis> which + &product-name; presents to the guest OS by default. + </para> + + <para> + ACPI is the current industry standard to allow OSes to recognize + hardware, configure motherboards and other devices and manage + power. As most computers contain this feature and Windows and + Linux support ACPI, it is also enabled by default in + &product-name;. ACPI can only be turned off using the command + line. See <xref linkend="vboxmanage-modifyvm" />. + </para> + + <warning> + <para> + All Windows OSes install different kernels, depending on + whether ACPI is available. This means that ACPI <emphasis>must + not be turned off</emphasis> after installation of a Windows + guest OS. However, turning it on after installation will have + no effect. + </para> + </warning> + + </sect2> + + <sect2 id="settings-processor"> + + <title>Processor Tab</title> + + <para> + On the <emphasis role="bold">Processor</emphasis> tab, you can + configure settings for the CPU used by the virtual machine. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Processor(s):</emphasis> Sets the + number of virtual CPU cores the guest OSes can see. + &product-name; supports symmetrical multiprocessing (SMP) + and can present up to 32 virtual CPU cores to each virtual + machine. + </para> + + <para> + You should not configure virtual machines to use more CPU + cores than are available physically. This includes real + cores, with no hyperthreads. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Execution Cap:</emphasis> Configures + the CPU execution cap. This limits the amount of time a host + CPU spends to emulate a virtual CPU. The default setting is + 100%, meaning that there is no limitation. A setting of 50% + implies a single virtual CPU can use up to 50% of a single + host CPU. Note that limiting the execution time of the + virtual CPUs may cause guest timing problems. + </para> + + <para> + A warning is displayed at the bottom of the Processor tab if + an Execution Cap setting is made that may affect system + performance. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable PAE/NX:</emphasis> Determines + whether the PAE and NX capabilities of the host CPU will be + exposed to the virtual machine. + </para> + + <para> + PAE stands for Physical Address Extension. Normally, if + enabled and supported by the OS, then even a 32-bit x86 CPU + can access more than 4 GB of RAM. This is made possible by + adding another 4 bits to memory addresses, so that with 36 + bits, up to 64 GB can be addressed. Some OSes, such as + Ubuntu Server, require PAE support from the CPU and cannot + be run in a virtual machine without it. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable Nested VT-x/AMD-V</emphasis>: + Enables nested virtualization, with passthrough of hardware + virtualization functions to the guest VM. + </para> + </listitem> + + </itemizedlist> + + <para> + With virtual machines running modern server OSes, &product-name; + also supports CPU hot-plugging. For details, see + <xref linkend="cpuhotplug" />. + </para> + + </sect2> + + <sect2 id="settings-acceleration"> + + <title>Acceleration Tab</title> + + <para> + On this tab, you can configure &product-name; to use hardware + virtualization extensions that your host CPU supports. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Paravirtualization + Interface:</emphasis> &product-name; provides + paravirtualization interfaces to improve time-keeping + accuracy and performance of guest OSes. The options + available are documented under the + <option>--paravirt-provider</option> option in + <xref linkend="vboxmanage-modifyvm" />. For further details + on the paravirtualization providers, see + <xref linkend="gimproviders" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Hardware Virtualization:</emphasis> + You can configure hardware virtualization features for each + virtual machine. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Enable Nested Paging:</emphasis> + If the host CPU supports the nested paging (AMD-V) or + EPT (Intel VT-x) features, then you can expect a + significant performance increase by enabling nested + paging in addition to hardware virtualization. For + technical details, see <xref linkend="nestedpaging" />. + For Intel EPT security recommendations, see + <xref linkend="sec-rec-cve-2018-3646" />. + </para> + </listitem> + + </itemizedlist> + + <para> + Advanced users may be interested in technical details about + hardware virtualization. See <xref linkend="hwvirt" />. + </para> + </listitem> + + </itemizedlist> + + <para> + In most cases, the default settings on the + <emphasis role="bold">Acceleration</emphasis> tab will work + well. &product-name; selects sensible defaults, depending on the + OS that you selected when you created the virtual machine. In + certain situations, however, you may want to change the + preconfigured defaults. + </para> + + </sect2> + + </sect1> + + <sect1 id="settings-display"> + + <title>Display Settings</title> + + <para> + The following tabs are available for configuring the display for a + virtual machine. + </para> + + <sect2 id="settings-screen"> + + <title>Screen Tab</title> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Video Memory:</emphasis> Sets the size + of the memory provided by the virtual graphics card + available to the guest, in MB. As with the main memory, the + specified amount will be allocated from the host's resident + memory. Based on the amount of video memory, higher + resolutions and color depths may be available. + </para> + + <para> + &vbox-mgr; will show a warning if the amount of video memory + is too small to be able to switch the VM into full screen + mode. The minimum value depends on the number of virtual + monitors, the screen resolution and the color depth of the + host display as well as on the use of <emphasis>3D + acceleration</emphasis> and <emphasis>2D video + acceleration</emphasis>. A rough estimate is + (<emphasis>color depth</emphasis> / 8) x <emphasis>vertical + pixels</emphasis> x <emphasis>horizontal pixels</emphasis> x + <emphasis>number of screens</emphasis> = <emphasis>number of + bytes</emphasis>. Extra memory may be required if display + acceleration is used. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Monitor Count:</emphasis> With this + setting, &product-name; can provide more than one virtual + monitor to a virtual machine. If a guest OS supports + multiple attached monitors, &product-name; can pretend that + multiple virtual monitors are present. Up to eight such + virtual monitors are supported. + </para> + + <para> + The output of the multiple monitors are displayed on the + host in multiple VM windows which are running side by side. + However, in full screen and seamless mode, they use the + available physical monitors attached to the host. As a + result, for full screen and seamless modes to work with + multiple monitors, you will need at least as many physical + monitors as you have virtual monitors configured, or + &product-name; will report an error. + </para> + + <para> + You can configure the relationship between guest and host + monitors using the <emphasis role="bold">View</emphasis> + menu by pressing Host key + Home when you are in full screen + or seamless mode. + </para> + + <para> + See also <xref linkend="KnownIssues" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Scale Factor:</emphasis> Enables + scaling of the display size. For multiple monitor displays, + you can set the scale factor for individual monitors, or + globally for all of the monitors. Use the slider to select a + scaling factor up to 200%. + </para> + + <para> + You can set a default scale factor for all VMs. Use the + <emphasis role="bold">Display</emphasis> tab in the + Preferences window. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Graphics Controller:</emphasis> + Specifies the graphics adapter type used by the guest VM. + Note that you must install the Guest Additions on the guest + VM to specify the VBoxSVGA or VMSVGA graphics controller. + The following options are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">VBoxSVGA:</emphasis> The default + graphics controller for new VMs that use Windows 7 or + later. + </para> + + <para> + This graphics controller improves performance and 3D + support when compared to the legacy VBoxVGA option. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VBoxVGA:</emphasis> Use this + graphics controller for legacy guest OSes. This is the + default graphics controller for Windows versions before + Windows 7 and for Oracle Solaris. + </para> + + <para> + 3D acceleration is not supported for this graphics + controller. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VMSVGA:</emphasis> Use this + graphics controller to emulate a VMware SVGA graphics + device. This is the default graphics controller for + Linux guests. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">None:</emphasis> Does not emulate + a graphics adapter type. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable 3D Acceleration:</emphasis> If + a virtual machine has Guest Additions installed, you can + select here whether the guest should support accelerated 3D + graphics. See <xref linkend="guestadd-3d" />. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="settings-remote-display"> + + <title>Remote Display Tab</title> + + <para> + On the <emphasis role="bold">Remote Display</emphasis> tab, if + the VirtualBox Remote Display Extension (VRDE) is installed, you + can enable the VRDP server that is built into &product-name;. + This enables you to connect to the console of the virtual + machine remotely with any standard RDP viewer, such as + <command>mstsc.exe</command> that comes with Microsoft Windows. + On Linux and Oracle Solaris systems you can use the standard + open source <command>rdesktop</command> program. These features + are described in <xref linkend="vrde" />. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Enable Server:</emphasis> Select this + check box and configure settings for the remote display + connection. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="settings-capture"> + + <title>Recording Tab</title> + + <para> + On the <emphasis role="bold">Recording</emphasis> tab you can + enable video and audio recording for a virtual machine and + change related settings. Note that these features can be enabled + and disabled while a VM is running. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Enable Recording:</emphasis> Select + this check box and select a <emphasis role="bold">Recording + Mode</emphasis> option. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Recording Mode:</emphasis> You can + choose to record video, audio, or both video and audio. + </para> + + <para> + Some settings on the + <emphasis role="bold">Recording</emphasis> tab may be grayed + out, depending on the <emphasis role="bold">Recording + Mode</emphasis> setting. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">File Path:</emphasis> The file where + the recording is saved. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Frame Size:</emphasis> The video + resolution of the recorded video, in pixels. The drop-down + list enables you to select from common frame sizes. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Frame Rate:</emphasis> Use the slider + to set the maximum number of video frames per second (FPS) + to record. Frames that have a higher frequency are skipped. + Increasing this value reduces the number of skipped frames + and increases the file size. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Video Quality:</emphasis> Use the + slider to set the the bit rate of the video in kilobits per + second. Increasing this value improves the appearance of the + video at the cost of an increased file size. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Audio Quality:</emphasis> Use the + slider to set the quality of the audio recording. Increasing + this value improves the audio quality at the cost of an + increased file size. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Screens:</emphasis> For a multiple + monitor display, you can select which screens to record + video from. + </para> + </listitem> + + </itemizedlist> + + <para> + As you adjust the video and audio recording settings, the + approximate output file size for a five minute video is shown. + </para> + + </sect2> + + </sect1> + + <sect1 id="settings-storage"> + + <title>Storage Settings</title> + + <para> + The <emphasis role="bold">Storage</emphasis> category in the VM + settings enables you to connect virtual hard disk, CD/DVD, and + floppy images and drives to your virtual machine. + </para> + + <para> + In a real computer, so-called <emphasis>storage + controllers</emphasis> connect physical disk drives to the rest of + the computer. Similarly, &product-name; presents virtual storage + controllers to a virtual machine. Under each controller, the + virtual devices, such as hard disks, CD/DVD or floppy drives, + attached to the controller are shown. + </para> + + <note> + <para> + This section gives a quick introduction to the &product-name; + storage settings. See <xref linkend="storage" /> for a full + description of the available storage settings in &product-name;. + </para> + </note> + + <para> + If you have used the <emphasis role="bold">Create Virtual + Machine</emphasis> wizard to create a machine, you will normally + see something like the following: + </para> + + <figure id="fig-storage-settings"> + <title>Storage Settings for a Virtual Machine</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/vm-settings-harddisk.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + Depending on the guest OS type that you selected when you created + the VM, a new VM includes the following storage devices: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">IDE controller.</emphasis> A virtual + CD/DVD drive is attached to device 0 on the secondary channel + of the IDE controller. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">SATA controller.</emphasis> This is a + modern type of storage controller for higher hard disk data + throughput, to which the virtual hard disks are attached. + Initially you will normally have one such virtual disk, but as + shown in the previous screenshot, you can have more than one. + Each is represented by a disk image file, such as a VDI file + in this example. + </para> + </listitem> + + </itemizedlist> + + <para> + If you created your VM with an older version of &product-name;, + the default storage layout may differ. You might then only have an + IDE controller to which both the CD/DVD drive and the hard disks + have been attached. This might also apply if you selected an older + OS type when you created the VM. Since older OSes do not support + SATA without additional drivers, &product-name; will make sure + that no such devices are present initially. See + <xref linkend="harddiskcontrollers" />. + </para> + + <para> + &product-name; also provides a <emphasis>floppy + controller</emphasis>. You cannot add devices other than floppy + drives to this controller. Virtual floppy drives, like virtual + CD/DVD drives, can be connected to either a host floppy drive, if + you have one, or a disk image, which in this case must be in RAW + format. + </para> + + <para> + You can modify these media attachments freely. For example, if you + wish to copy some files from another virtual disk that you + created, you can connect that disk as a second hard disk, as in + the above screenshot. You could also add a second virtual CD/DVD + drive, or change where these items are attached. The following + options are available: + </para> + + <itemizedlist> + + <listitem> + <para> + To <emphasis role="bold">add another virtual hard disk, or a + CD/DVD or floppy drive</emphasis>, select the storage + controller to which it should be added (such as IDE, SATA, + SCSI, SAS, floppy controller) and then click the + <emphasis role="bold">Add Disk</emphasis> button below the + tree. You can then either select <emphasis role="bold">Optical + Drive</emphasis> or <emphasis role="bold">Hard + Disk</emphasis>. If you clicked on a floppy controller, you + can add a floppy drive instead. Alternatively, right-click on + the storage controller and select a menu item there. + </para> + + <para> + A dialog is displayed, enabling you to select an existing disk + image file or to create a new disk image file. Depending on + the type of disk image, the dialog is called + <emphasis role="bold">Hard Disk Selector</emphasis>, + <emphasis role="bold">Optical Disk Selector</emphasis>, or + <emphasis role="bold">Floppy Disk Selector</emphasis>. + </para> + + <para> + See <xref linkend="vdidetails"/> for information on the image + file types that are supported by &product-name;. + </para> + + <para> + For virtual CD/DVD drives, the image files will typically be + in the standard ISO format instead. Most commonly, you will + select this option when installing an OS from an ISO file that + you have obtained from the Internet. For example, most Linux + distributions are available in this way. + </para> + + <para> + Depending on the type of disk image, you can set the following + <emphasis role="bold">Attributes</emphasis> for the disk image + in the right part of the Storage settings page: + </para> + + <itemizedlist> + + <listitem> + <para> + The <emphasis role="bold">device slot</emphasis> of the + controller that the virtual disk is connected to. IDE + controllers have four slots: primary device 0, primary + device 1, secondary device 0, and secondary device 1. By + contrast, SATA and SCSI controllers offer you up to 30 + slots for attaching virtual devices. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Solid-state Drive</emphasis> + presents a virtual disk to the guest as a solid-state + device. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Hot-pluggable</emphasis> presents a + virtual disk to the guest as a hot-pluggable device. + </para> + </listitem> + + <listitem> + <para> + For virtual CD/DVD drives, you can select + <emphasis role="bold">Live CD/DVD</emphasis>. This means + that the virtual optical disk is not removed from when the + guest system ejects it. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + To <emphasis role="bold">remove an attachment</emphasis>, + either select it and click on the + <emphasis role="bold">Remove</emphasis> icon at the bottom, or + right-click on it and select the menu item. + </para> + </listitem> + + </itemizedlist> + + <para> + Removable media, such as CD/DVDs and floppies, can be changed + while the guest is running. Since the + <emphasis role="bold">Settings</emphasis> window is not available + at that time, you can also access these settings from the + <emphasis role="bold">Devices</emphasis> menu of your virtual + machine window. + </para> + + </sect1> + + <sect1 id="settings-audio"> + + <title>Audio Settings</title> + + <para> + The <emphasis role="bold">Audio</emphasis> section in a virtual + machine's <emphasis role="bold">Settings</emphasis> window + determines whether the VM will detect a connected sound card, and + if the audio output should be played on the host system. + </para> + + <para> + To enable audio for a guest, select the + <emphasis role="bold">Enable Audio</emphasis> check box. The + following settings are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Host Audio Driver:</emphasis> The audio + driver that &product-name; uses on the host. + </para> + + <para> + The <emphasis role="bold">Default</emphasis> option is enabled + by default for all new VMs. This option selects the best audio + driver for the host platform automatically. This enables you + to move VMs between different platforms without having to + change the audio driver. + </para> + + <para> + On a Linux host, depending on your host configuration, you can + select between the OSS, ALSA, or the PulseAudio subsystem. On + newer Linux distributions, the PulseAudio subsystem is + preferred. + </para> + + <para> + Only OSS is supported on Oracle Solaris hosts. The Oracle + Solaris Audio audio backend is no longer supported on Oracle + Solaris hosts. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Audio Controller:</emphasis> You can + choose between the emulation of an Intel AC'97 controller, an + Intel HD Audio controller, or a SoundBlaster 16 card. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable Audio Output:</emphasis> Enables + audio output only for the VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable Audio Input:</emphasis> Enables + audio input only for the VM. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="settings-network"> + + <title>Network Settings</title> + + <para> + The <emphasis role="bold">Network</emphasis> section in a virtual + machine's <emphasis role="bold">Settings</emphasis> window enables + you to configure how &product-name; presents virtual network cards + to your VM, and how they operate. + </para> + + <para> + When you first create a virtual machine, &product-name; by default + enables one virtual network card and selects the Network Address + Translation (NAT) mode for it. This way the guest can connect to + the outside world using the host's networking and the outside + world can connect to services on the guest which you choose to + make visible outside of the virtual machine. + </para> + + <para> + This default setup is good for the majority of &product-name; + users. However, &product-name; is extremely flexible in how it can + virtualize networking. It supports many virtual network cards per + virtual machine. The first four virtual network cards can be + configured in detail in &vbox-mgr;. Additional network cards can + be configured using the <command>VBoxManage</command> command. + </para> + + <para> + Many networking options are available. See + <xref linkend="networkingdetails" /> for more information. + </para> + + </sect1> + + <sect1 id="serialports"> + + <title>Serial Ports</title> + + <para> + &product-name; supports the use of virtual serial ports in a + virtual machine. + </para> + + <para> + Ever since the original IBM PC, personal computers have been + equipped with one or two serial ports, also called COM ports by + DOS and Windows. Serial ports were commonly used with modems, and + some computer mice used to be connected to serial ports before USB + became commonplace. + </para> + + <para> + While serial ports are no longer as common as they used to be, + there are still some important uses left for them. For example, + serial ports can be used to set up a primitive network over a + null-modem cable, in case Ethernet is not available. Also, serial + ports are indispensable for system programmers needing to do + kernel debugging, since kernel debugging software usually + interacts with developers over a serial port. With virtual serial + ports, system programmers can do kernel debugging on a virtual + machine instead of needing a real computer to connect to. + </para> + + <para> + If a virtual serial port is enabled, the guest OS sees a standard + 16550A compatible UART device. Other UART types can be configured + using the <command>VBoxManage modifyvm</command> command. Both + receiving and transmitting data is supported. How this virtual + serial port is then connected to the host is configurable, and the + details depend on your host OS. + </para> + + <para> + You can use either the Settings tabs or the + <command>VBoxManage</command> command to set up virtual serial + ports. For the latter, see <xref linkend="vboxmanage-modifyvm" /> + for information on the <option>--uart</option>, + <option>--uart-mode</option> and <option>--uart-type</option> + options. + </para> + + <para> + You can configure up to four virtual serial ports per virtual + machine. For each device, you must set the following: + </para> + + <orderedlist> + + <listitem> + <para> + <emphasis role="bold">Port Number:</emphasis> This determines + the serial port that the virtual machine should see. For best + results, use the traditional values as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + COM1: I/O base 0x3F8, IRQ 4 + </para> + </listitem> + + <listitem> + <para> + COM2: I/O base 0x2F8, IRQ 3 + </para> + </listitem> + + <listitem> + <para> + COM3: I/O base 0x3E8, IRQ 4 + </para> + </listitem> + + <listitem> + <para> + COM4: I/O base 0x2E8, IRQ 3 + </para> + </listitem> + + </itemizedlist> + + <para> + You can also configure a user-defined serial port. Enter an + I/O base address and interrupt (IRQ). + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Port Mode:</emphasis> What the virtual + port is connected to. For each virtual serial port, you have + the following options: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Disconnected:</emphasis> The guest + will see the device, but it will behave as if no cable had + been connected to it. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Host Device:</emphasis> Connects the + virtual serial port to a physical serial port on your + host. On a Windows host, this will be a name like + <literal>COM1</literal>. On Linux or Oracle Solaris hosts, + it will be a device node like + <filename>/dev/ttyS0</filename>. &product-name; will then + simply redirect all data received from and sent to the + virtual serial port to the physical device. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Host Pipe:</emphasis> Configure + &product-name; to connect the virtual serial port to a + software pipe on the host. This depends on your host OS, + as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + On a Windows host, data will be sent and received + through a named pipe. The pipe name must be in the + format + <filename>\\.\pipe\<replaceable>name</replaceable></filename> + where <replaceable>name</replaceable> should identify + the virtual machine but may be freely chosen. + </para> + </listitem> + + <listitem> + <para> + On a Mac OS, Linux, or Oracle Solaris host, a local + domain socket is used instead. The socket filename + must be chosen such that the user running + &product-name; has sufficient privileges to create and + write to it. The <filename>/tmp</filename> directory + is often a good candidate. + </para> + + <para> + On Linux there are various tools which can connect to + a local domain socket or create one in server mode. + The most flexible tool is <command>socat</command> and + is available as part of many distributions. + </para> + </listitem> + + </itemizedlist> + + <para> + In this case, you can configure whether &product-name; + should create the named pipe, or the local domain socket + non-Windows hosts, itself or whether &product-name; should + assume that the pipe or socket exists already. With the + <command>VBoxManage</command> command-line options, this + is referred to as server mode or client mode, + respectively. + </para> + + <para> + For a direct connection between two virtual machines, + corresponding to a null-modem cable, simply configure one + VM to create a pipe or socket and another to attach to it. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Raw File:</emphasis> Send the + virtual serial port output to a file. This option is very + useful for capturing diagnostic output from a guest. Any + file may be used for this purpose, as long as the user + running &product-name; has sufficient privileges to create + and write to the file. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">TCP:</emphasis> Useful for + forwarding serial traffic over TCP/IP, acting as a server, + or it can act as a TCP client connecting to other servers. + This option enables a remote machine to directly connect + to the guest's serial port using TCP. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">TCP Server:</emphasis> Deselect + the <emphasis role="bold">Connect to Existing + Pipe/Socket</emphasis> check box and specify the port + number in the + <emphasis role="bold">Path/Address</emphasis> field. + This is typically 23 or 2023. Note that on UNIX-like + systems you will have to use a port a number greater + than 1024 for regular users. + </para> + + <para> + The client can use software such as + <command>PuTTY</command> or the + <command>telnet</command> command line tool to access + the TCP Server. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">TCP Client:</emphasis> To create + a virtual null-modem cable over the Internet or LAN, + the other side can connect using TCP by specifying + <literal><replaceable>hostname</replaceable>:<replaceable>port</replaceable></literal> + in the <emphasis role="bold">Path/Address</emphasis> + field. The TCP socket will act in client mode if you + select the <emphasis role="bold">Connect to Existing + Pipe/Socket</emphasis> check box. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + </listitem> + + </orderedlist> + + <para> + Up to four serial ports can be configured per virtual machine, but + you can pick any port numbers out of the above. However, serial + ports cannot reliably share interrupts. If both ports are to be + used at the same time, they must use different interrupt levels, + for example COM1 and COM2, but not COM1 and COM3. + </para> + + </sect1> + + <sect1 id="usb-support"> + + <title>USB Support</title> + + <sect2 id="settings-usb"> + + <title>USB Settings</title> + + <para> + The <emphasis role="bold">USB</emphasis> section in a virtual + machine's <emphasis role="bold">Settings</emphasis> window + enables you to configure &product-name;'s sophisticated USB + support. + </para> + + <para> + &product-name; can enable virtual machines to access the USB + devices on your host directly. To achieve this, &product-name; + presents the guest OS with a virtual USB controller. As soon as + the guest system starts using a USB device, it will appear as + unavailable on the host. + </para> + + <note> + <itemizedlist> + + <listitem> + <para> + Be careful with USB devices that are currently in use on + the host. For example, if you allow your guest to connect + to your USB hard disk that is currently mounted on the + host, when the guest is activated, it will be disconnected + from the host without a proper shutdown. This may cause + data loss. + </para> + </listitem> + + <listitem> + <para> + Oracle Solaris hosts have a few known limitations + regarding USB support. See <xref linkend="KnownIssues" />. + </para> + </listitem> + + </itemizedlist> + </note> + + <para> + In addition to allowing a guest access to your local USB + devices, &product-name; even enables your guests to connect to + remote USB devices by use of the VirtualBox Remote Desktop + Extension (VRDE). See <xref linkend="usb-over-rdp" />. + </para> + + <para> + To enable USB for a VM, select the <emphasis role="bold">Enable + USB Controller</emphasis> check box. The following settings are + available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">USB Controller:</emphasis> Selects a + controller with the specified level of USB support, as + follows: + </para> + + <itemizedlist> + + <listitem> + <para> + OHCI for USB 1.1 + </para> + </listitem> + + <listitem> + <para> + EHCI for USB 2.0. This also enables OHCI. + </para> + </listitem> + + <listitem> + <para> + xHCI for USB 3.0. This supports all USB speeds. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">USB Device Filters:</emphasis> When + USB support is enabled for a VM, you can determine in detail + which devices will be automatically attached to the guest. + For this, you can create filters by specifying certain + properties of the USB device. USB devices with a matching + filter will be automatically passed to the guest once they + are attached to the host. USB devices without a matching + filter can be passed manually to the guest, for example by + using the <emphasis role="bold">Devices</emphasis>, + <emphasis role="bold">USB</emphasis> menu. + </para> + + <para> + Clicking on the <emphasis role="bold">+</emphasis> button to + the right of the <emphasis role="bold">USB Device + Filters</emphasis> window creates a new filter. You can give + the filter a name, for later reference, and specify the + filter criteria. The more criteria you specify, the more + precisely devices will be selected. For instance, if you + specify only a vendor ID of 046d, all devices produced by + Logitech will be available to the guest. If you fill in all + fields, on the other hand, the filter will only apply to a + particular device model from a particular vendor, and not + even to other devices of the same type with a different + revision and serial number. + </para> + + <para> + In detail, the following criteria are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Vendor and Product ID.</emphasis> + With USB, each vendor of USB products carries an + identification number that is unique world-wide, called + the <emphasis>vendor ID</emphasis>. Similarly, each line + of products is assigned a <emphasis>product + ID</emphasis> number. Both numbers are commonly written + in hexadecimal, and a colon separates the vendor from + the product ID. For example, + <literal>046d:c016</literal> stands for Logitech as a + vendor, and the M-UV69a Optical Wheel Mouse product. + </para> + + <para> + Alternatively, you can also specify + <emphasis role="bold">Manufacturer</emphasis> and + <emphasis role="bold">Product</emphasis> by name. + </para> + + <para> + To list all the USB devices that are connected to your + host machine with their respective vendor IDs and + product IDs, use the following command: + </para> + +<screen>VBoxManage list usbhost</screen> + + <para> + On Windows, you can also see all USB devices that are + attached to your system in the Device Manager. On Linux, + you can use the <command>lsusb</command> command. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Serial Number.</emphasis> While + vendor ID and product ID are quite specific to identify + USB devices, if you have two identical devices of the + same brand and product line, you will also need their + serial numbers to filter them out correctly. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Remote.</emphasis> This setting + specifies whether the device will be local only, remote + only, such as over VRDP, or either. + </para> + </listitem> + + </itemizedlist> + + <para> + On a Windows host, you will need to unplug and reconnect a + USB device to use it after creating a filter for it. + </para> + + <para> + As an example, you could create a new USB filter and specify + a vendor ID of 046d for Logitech, Inc, a manufacturer index + of 1, and "not remote". Then any USB devices on the host + system produced by Logitech, Inc with a manufacturer index + of 1 will be visible to the guest system. + </para> + + <para> + Several filters can select a single device. For example, a + filter which selects all Logitech devices, and one which + selects a particular webcam. + </para> + + <para> + You can deactivate filters without deleting them by + deselecting the check box next to the filter name. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="usb-implementation-notes"> + + <title>Implementation Notes for Windows and Linux Hosts</title> + + <para> + On Windows hosts, a kernel mode device driver provides USB proxy + support. It implements both a USB monitor, which enables + &product-name; to capture devices when they are plugged in, and + a USB device driver to claim USB devices for a particular + virtual machine. System reboots are not necessary after + installing the driver. Also, you do not need to replug devices + for &product-name; to claim them. + </para> + + <para> + On supported Linux hosts, &product-name; accesses USB devices + through special files in the file system. When &product-name; is + installed, these are made available to all users in the + <literal>vboxusers</literal> system group. In order to be able + to access USB from guest systems, make sure that you are a + member of this group. + </para> + + </sect2> + + </sect1> + + <sect1 id="shared-folders"> + + <title>Shared Folders</title> + + <para> + Shared folders enable you to easily exchange data between a + virtual machine and your host. This feature requires that the + &product-name; Guest Additions be installed in a virtual machine + and is described in detail in <xref linkend="sharedfolders" />. + </para> + + </sect1> + + <sect1 id="user-interface"> + + <title>User Interface</title> + + <para> + The <emphasis role="bold">User Interface</emphasis> section + enables you to change certain aspects of the user interface of the + selected VM. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Menu Bar:</emphasis> This widget enables + you to disable a complete menu, by clicking on the menu name + to deselect it. Menu entries can be disabled, by deselecting + the check box next to the entry. On Windows and Linux hosts, + the complete menu bar can be disabled by deselecting the check + box on the right. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Mini ToolBar:</emphasis> In full screen + or seamless mode, &product-name; can display a small toolbar + that contains some of the items that are normally available + from the virtual machine's menu bar. This toolbar reduces + itself to a small gray line unless you move the mouse over it. + With the toolbar, you can return from full screen or seamless + mode, control machine execution, or enable certain devices. If + you do not want to see the toolbar, disable the + <emphasis role="bold">Show in Full Screen/Seamless</emphasis> + setting. + </para> + + <para> + The <emphasis role="bold">Show at Top of Screen</emphasis> + setting enables you to show the toolbar at the top of the + screen, instead of showing it at the bottom. + </para> + + <para> + The Mini Toolbar is not available on macOS hosts. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Status Bar:</emphasis> This widget + enables you to disable and reorder icons on the status bar. + Deselect the check box of an icon to disable it, or rearrange + icons by dragging and dropping the icon. To disable the + complete status bar deselect the check box on the left. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="efi"> + + <title>Alternative Firmware (EFI)</title> + + <para> + &product-name; includes experimental support for the Extensible + Firmware Interface (EFI), which is an industry standard intended + to replace the legacy BIOS as the primary interface for + bootstrapping computers and certain system services later. + </para> + + <para> + By default, &product-name; uses the BIOS firmware for virtual + machines. To use EFI for a given virtual machine, you can enable + EFI in the machine's <emphasis role="bold">Settings</emphasis> + window. See <xref linkend="settings-motherboard"/>. Alternatively, + use the <command>VBoxManage</command> command line interface as + follows: + </para> + +<screen>VBoxManage modifyvm "VM name" --firmware efi</screen> + + <para> + To switch back to using the BIOS: + </para> + +<screen>VBoxManage modifyvm "VM name" --firmware bios</screen> + + <para> + One notable user of EFI is Apple Mac OS X. More recent Linux + versions and Windows releases, starting with Vista, also offer + special versions that can be booted using EFI. + </para> + + <para> + Another possible use of EFI in &product-name; is development and + testing of EFI applications, without booting any OS. + </para> + + <para> + Note that the &product-name; EFI support is experimental and will + be enhanced as EFI matures and becomes more widespread. Mac OS X, + Linux, and newer Windows guests are known to work fine. Windows 7 + guests are unable to boot with the &product-name; EFI + implementation. + </para> + + <sect2 id="efividmode"> + + <title>Video Modes in EFI</title> + + <para> + EFI provides two distinct video interfaces: GOP (Graphics Output + Protocol) and UGA (Universal Graphics Adapter). Modern OSes, + such as Mac OS X, generally use GOP, while some older ones still + use UGA. &product-name; provides a configuration option to + control the graphics resolution for both interfaces, making the + difference mostly irrelevant for users. + </para> + + <para> + The default resolution is 1024x768. To select a graphics + resolution for EFI, use the following + <command>VBoxManage</command> command: + </para> + +<screen>VBoxManage setextradata "VM name" VBoxInternal2/EfiGraphicsResolution HxV</screen> + + <para> + Determine the horizontal resolution H and the vertical + resolution V from the following list of default resolutions: + </para> + + <variablelist> + + <varlistentry> + <term> + VGA + </term> + + <listitem> + <para> + 640x480, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + SVGA + </term> + + <listitem> + <para> + 800x600, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + XGA + </term> + + <listitem> + <para> + 1024x768, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + XGA+ + </term> + + <listitem> + <para> + 1152x864, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + HD + </term> + + <listitem> + <para> + 1280x720, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WXGA + </term> + + <listitem> + <para> + 1280x800, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + SXGA + </term> + + <listitem> + <para> + 1280x1024, 32bpp, 5:4 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + SXGA+ + </term> + + <listitem> + <para> + 1400x1050, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WXGA+ + </term> + + <listitem> + <para> + 1440x900, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + HD+ + </term> + + <listitem> + <para> + 1600x900, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + UXGA + </term> + + <listitem> + <para> + 1600x1200, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WSXGA+ + </term> + + <listitem> + <para> + 1680x1050, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + Full HD + </term> + + <listitem> + <para> + 1920x1080, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WUXGA + </term> + + <listitem> + <para> + 1920x1200, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + DCI 2K + </term> + + <listitem> + <para> + 2048x1080, 32bpp, 19:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + Full HD+ + </term> + + <listitem> + <para> + 2160x1440, 32bpp, 3:2 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + Unnamed + </term> + + <listitem> + <para> + 2304x1440, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + QHD + </term> + + <listitem> + <para> + 2560x1440, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WQXGA + </term> + + <listitem> + <para> + 2560x1600, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + QWXGA+ + </term> + + <listitem> + <para> + 2880x1800, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + QHD+ + </term> + + <listitem> + <para> + 3200x1800, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WQSXGA + </term> + + <listitem> + <para> + 3200x2048, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + 4K UHD + </term> + + <listitem> + <para> + 3840x2160, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WQUXGA + </term> + + <listitem> + <para> + 3840x2400, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + DCI 4K + </term> + + <listitem> + <para> + 4096x2160, 32bpp, 19:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + HXGA + </term> + + <listitem> + <para> + 4096x3072, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + UHD+ + </term> + + <listitem> + <para> + 5120x2880, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WHXGA + </term> + + <listitem> + <para> + 5120x3200, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WHSXGA + </term> + + <listitem> + <para> + 6400x4096, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + HUXGA + </term> + + <listitem> + <para> + 6400x4800, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + 8K UHD2 + </term> + + <listitem> + <para> + 7680x4320, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + If this list of default resolution does not cover your needs, + see <xref linkend="customvesa" />. Note that the color depth + value specified in a custom video mode must be specified. Color + depths of 8, 16, 24, and 32 are accepted. EFI assumes a color + depth of 32 by default. + </para> + + <para> + The EFI default video resolution settings can only be changed + when the VM is powered off. + </para> + + </sect2> + + <sect2 id="efibootargs"> + + <title>Specifying Boot Arguments</title> + + <para> + It is currently not possible to manipulate EFI variables from + within a running guest. For example, setting the + <literal>boot-args</literal> variable by running the + <command>nvram</command> tool in a Mac OS X guest will not work. + As an alternative method, + <literal>VBoxInternal2/EfiBootArgs</literal> extradata can be + passed to a VM in order to set the <literal>boot-args</literal> + variable. To change the <literal>boot-args</literal> EFI + variable, use the following command: + </para> + +<screen>VBoxManage setextradata "VM name" VBoxInternal2/EfiBootArgs <value></screen> + + </sect2> + + </sect1> + +</chapter> diff --git a/doc/manual/en_US/user_ChangeLog.xml b/doc/manual/en_US/user_ChangeLog.xml new file mode 100644 index 00000000..928ef422 --- /dev/null +++ b/doc/manual/en_US/user_ChangeLog.xml @@ -0,0 +1,69 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="ChangeLog"> + + <title>Change Log</title> + + <para> + This section summarizes the changes between &product-name; versions. + Note that this change log is not exhaustive and not all changes are + listed. + </para> + + <para> + &product-name; version numbers consist of three numbers separated by + dots where the first and second number represent the major version + and the third number the minor version. Minor version numbers of + official releases are always even. An odd minor version number + represents an internal development or test build. In addition, each + build contains a revision number. + </para> + + <xi:include href="user_ChangeLogImpl.xml" xpointer="xpointer(/chapter/*)" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <sect1 id="change-log-older"> + + <title>Change Logs for Legacy Versions</title> + + <para> + To view the change log for a legacy version of VirtualBox see the + documentation for the relevant &product-name; release. + </para> + + <para> + Change logs are also available at: + </para> + + <para> + <ulink url="https://www.virtualbox.org/wiki/Changelog" />. + </para> + + </sect1> + +</chapter> diff --git a/doc/manual/en_US/user_Frontends.xml b/doc/manual/en_US/user_Frontends.xml new file mode 100644 index 00000000..f037312e --- /dev/null +++ b/doc/manual/en_US/user_Frontends.xml @@ -0,0 +1,1208 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="remotevm"> + + <title>Remote Virtual Machines</title> + + <sect1 id="vrde"> + + <title>Remote Display (VRDP Support)</title> + + <para> + &product-name; can display virtual machines remotely, meaning that + a virtual machine can execute on one computer even though the + machine will be displayed on a second computer, and the machine + will be controlled from there as well, as if the virtual machine + was running on that second computer. + </para> + + <para> + For maximum flexibility, &product-name; implements remote machine + display through a generic extension interface called the + VirtualBox Remote Desktop Extension (VRDE). The base open source + &product-name; package only provides this interface, while + implementations can be supplied by third parties with + &product-name; extension packages, which must be installed + separately from the base package. See + <xref linkend="intro-installing" />. + </para> + + <para> + Oracle provides support for the VirtualBox Remote Display Protocol + (VRDP) in such an &product-name; extension package. + </para> + + <para> + VRDP is a backwards-compatible extension to Microsoft's Remote + Desktop Protocol (RDP). As a result, you can use any standard RDP + client to control the remote VM. + </para> + + <para> + Even when the extension is installed, the VRDP server is disabled + by default. It can easily be enabled on a per-VM basis either from + &vbox-mgr; in the <emphasis role="bold">Display</emphasis> + settings, see <xref linkend="settings-display" />, or with the + <command>VBoxManage</command> command, as follows: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde on</screen> + + <para> + By default, the VRDP server uses TCP port <literal>3389</literal>. + You will need to change the default port if you run more than one + VRDP server, since the port can only be used by one server at a + time. You might also need to change it on Windows hosts since the + default port might already be used by the RDP server that is built + into Windows itself. Ports 5000 through 5050 are typically not + used and might be a good choice. + </para> + + <para> + The port can be changed either in the + <emphasis role="bold">Display</emphasis> settings of the graphical + user interface or with the <option>--vrde-port</option> option of + the <command>VBoxManage modifyvm</command> command. You can + specify a comma-separated list of ports or ranges of ports. Use a + dash between two port numbers to specify a range. The VRDP server + will bind to <emphasis>one</emphasis> of the available ports from + the specified list. For example, <command>VBoxManage modifyvm + <replaceable>VM-name</replaceable> --vrde-port + 5000,5010-5012</command> configures the server to bind to one of + the ports 5000, 5010, 5011, or 5012. See + <xref linkend="vboxmanage-modifyvm" />. + </para> + + <para> + The actual port used by a running VM can be either queried with + the <command>VBoxManage showvminfo</command> command or seen in + &vbox-mgr; on the <emphasis role="bold">Runtime</emphasis> tab of + the <emphasis role="bold">Session Information</emphasis> dialog, + which is accessible from the + <emphasis role="bold">Machine</emphasis> menu of the VM window. + </para> + + <para> + &product-name; supports IPv6. If the host OS supports IPv6 the + VRDP server will automatically listen for IPv6 connections in + addition to IPv4. + </para> + + <sect2 id="rdp-viewers"> + + <title>Common Third-Party RDP Viewers</title> + + <para> + Since VRDP is backwards-compatible to RDP, you can use any + standard RDP viewer to connect to such a remote virtual machine. + For this to work, you must specify the IP address of your + <emphasis>host</emphasis> system, not of the virtual machine, as + the server address to connect to. You must also specify the port + number that the VRDP server is using. + </para> + + <para> + The following examples are for the most common RDP viewers: + </para> + + <itemizedlist> + + <listitem> + <para> + On Windows, you can use the Microsoft Terminal Services + Connector, <command>mstsc.exe</command>, that is included + with Windows. Press the Windows key + R, to display the + <emphasis role="bold">Run</emphasis> dialog. Enter + <command>mstsc</command> to start the program. You can also + find the program in <emphasis role="bold">Start</emphasis>, + <emphasis role="bold">All Programs</emphasis>, + <emphasis role="bold">Accessories</emphasis>, + <emphasis role="bold">Remote Desktop Connection</emphasis>. + If you use the <emphasis role="bold">Run</emphasis> dialog, + you can enter options directly. For example: + </para> + +<screen>mstsc 1.2.3.4:3389</screen> + + <para> + Replace <literal>1.2.3.4</literal> with the host IP address, + and <literal>3389</literal> with a different port, if + necessary. + </para> + + <note> + <itemizedlist> + + <listitem> + <para> + IPv6 addresses must be enclosed in square brackets to + specify a port. For example: <literal>mstsc + [fe80::1:2:3:4]:3389</literal> + </para> + </listitem> + + <listitem> + <para> + When connecting to localhost in order to test the + connection, the addresses <literal>localhost</literal> + and <literal>127.0.0.1</literal> might not work using + <command>mstsc.exe</command>. Instead, the address + <literal>127.0.0.2[:3389]</literal> has to be used. + </para> + </listitem> + + </itemizedlist> + </note> + </listitem> + + <listitem> + <para> + On other systems, you can use the standard open source + <command>rdesktop</command> program. This ships with most + Linux distributions. + </para> + + <para> + With <command>rdesktop</command>, use a command line such as + the following: + </para> + +<screen>$ rdesktop -a 16 -N 1.2.3.4:3389</screen> + + <para> + Replace <literal>1.2.3.4</literal> with the host IP address, + and <literal>3389</literal> with a different port, if + necessary. The <option>-a 16</option> option requests a + color depth of 16 bits per pixel, which we recommend. For + best performance, after installation of the guest operating + system, you should set its display color depth to the same + value. The <option>-N</option> option enables use of the + NumPad keys. + </para> + </listitem> + + <listitem> + <para> + You can use the Remmina remote desktop client with VRDP. + This application is included with some Linux distributions, + such as Debian and Ubuntu. + </para> + </listitem> + + <listitem> + <para> + If you run the KDE desktop, you can use + <command>krdc</command>, the KDE RDP viewer. A typical + command line is as follows: + </para> + +<screen>$ krdc rdp://1.2.3.4:3389</screen> + + <para> + Replace <literal>1.2.3.4</literal> with the host IP address, + and <literal>3389</literal> with a different port, if + necessary. The <literal>rdp:// </literal> prefix is required + with <command>krdc</command> to switch it into RDP mode. + </para> + </listitem> + + <listitem> + <para> + With Sun Ray thin clients you can use + <command>uttsc</command>, which is part of the Sun Ray + Windows Connector package. See the Sun Ray documentation for + details. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="vboxheadless"> + + <title>VBoxHeadless, the Remote Desktop Server</title> + + <para> + While any VM started from &vbox-mgr; is capable of running + virtual machines remotely, it is not convenient to have to run + the full GUI if you never want to have VMs displayed locally in + the first place. In particular, if you are running server + hardware whose only purpose is to host VMs, and all your VMs are + supposed to run remotely over VRDP, then it is pointless to have + a graphical user interface on the server at all. This is + especially true for Linux or Oracle Solaris hosts, as the + &vbox-mgr; comes with dependencies on the Qt and SDL libraries. + This is inconvenient if you would rather not have the X Window + system on your server at all. + </para> + + <para> + &product-name; therefore comes with a front-end called + <command>VBoxHeadless</command>, which produces no visible + output on the host at all, but still can optionally deliver VRDP + data. This front-end has no dependencies on the X Window system + on Linux and Oracle Solaris hosts. + </para> + + <note> + <para> + In legacy releases of &product-name;, the headless server was + called <command>VBoxVRDP</command>. For backwards + compatibility, the &product-name; installation still includes + an executable with that name. + </para> + </note> + + <para> + To start a virtual machine with <command>VBoxHeadless</command>, + you have the following options: + </para> + + <itemizedlist> + + <listitem> + <para> + Use the <command>VBoxManage</command> command, as follows: + </para> + +<screen>$ VBoxManage startvm <replaceable>VM-name</replaceable> --type headless</screen> + + <para> + The <option>--type</option> option causes &product-name; to + use <command>VBoxHeadless</command> as the front-end to the + internal virtualization engine, instead of the Qt front-end. + </para> + </listitem> + + <listitem> + <para> + Use the <command>VBoxHeadless</command> command, as follows: + </para> + +<screen>VBoxHeadless --startvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></screen> + + <para> + This way of starting the VM helps troubleshooting problems + reported by <command>VBoxManage startvm</command>, because + you can sometimes see more detailed error messages, + especially for early failures before the VM execution is + started. In normal situations <command>VBoxManage + startvm</command> is preferred, since it runs the VM + directly as a background process which has to be done + explicitly when directly starting with + <command>VBoxHeadless</command>. The full documentation of + the command is in <xref linkend="man_vboxheadless"/>. + </para> + </listitem> + + <listitem> + <para> + Start <command>VBoxHeadless</command> from &vbox-mgr;, by + pressing the Shift key when starting a virtual machine or by + selecting <emphasis role="bold">Headless Start</emphasis> + from the <emphasis role="bold">Machine</emphasis> menu. + </para> + </listitem> + + </itemizedlist> + + <para> + When you use the <command>VBoxHeadless</command> command to + start a VM, the VRDP server will be enabled according to the VM + configuration. You can override the VM's setting using + <option>--vrde</option> command line parameter. To enable the + VRDP server, start the VM as follows: + </para> + +<screen>VBoxHeadless --startvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> --vrde on</screen> + + <para> + To disable the VRDP server: + </para> + +<screen>VBoxHeadless --startvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> --vrde off</screen> + + <para> + To have the VRDP server enabled depending on the VM + configuration, as for other front-ends: + </para> + +<screen>VBoxHeadless --startvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> --vrde config</screen> + + <para> + This command is the same as the following: + </para> + +<screen>VBoxHeadless --startvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></screen> + + <para> + If you start the VM with <command>VBoxManage startvm</command> + then the configuration settings of the VM are always used. + </para> + + </sect2> + + <sect2 id="headless-vm-steps"> + + <title>Step by Step: Creating a Virtual Machine on a Headless Server</title> + + <para> + The following instructions describe how to create a virtual + machine on a headless server over a network connection. This + example creates a virtual machine, establishes an RDP connection + and installs a guest operating system. All of these tasks are + done without having to touch the headless server. You need the + following prerequisites: + </para> + + <itemizedlist> + + <listitem> + <para> + &product-name; on a server machine with a supported host + operating system. The &product-name; Extension Pack for the + VRDP server must be installed, see <xref linkend="vrde"/>. + The procedures assume a Linux server is used. + </para> + </listitem> + + <listitem> + <para> + An ISO file accessible from the server, containing the + installation data for the guest operating system to install. + Windows XP is used in the example. + </para> + </listitem> + + <listitem> + <para> + A terminal connection to that host through which you can + access a command line, such as <command>ssh</command>. + </para> + </listitem> + + <listitem> + <para> + An RDP viewer on the remote client. See + <xref linkend="rdp-viewers" /> for examples. + </para> + </listitem> + + </itemizedlist> + + <para> + Note that on the server machine, since we will only use the + headless server, Qt and the X Window system are not required. + </para> + + <orderedlist> + + <listitem> + <para> + On the headless server, create a new virtual machine. For + example: + </para> + +<screen>VBoxManage createvm --name "Windows XP" --ostype WindowsXP --register</screen> + + <para> + If you do not specify <option>--register</option>, you will + have to manually use the <command>registervm</command> + command later. + </para> + + <para> + You do not need to specify <option>--ostype</option>, but + doing so selects some sensible default values for certain VM + parameters. For example, the RAM size and the type of the + virtual network device. To get a complete list of supported + operating systems you can use the following command: + </para> + +<screen>VBoxManage list ostypes</screen> + </listitem> + + <listitem> + <para> + Make sure the settings for the VM are appropriate for the + guest operating system that we will install. For example: + </para> + +<screen>VBoxManage modifyvm "Windows XP" --memory 256 --acpi on --boot1 dvd --nic1 nat</screen> + </listitem> + + <listitem> + <para> + Create a virtual hard disk for the VM. For example, to + create a 10 GB virtual hard disk: + </para> + +<screen>VBoxManage createhd --filename "WinXP.vdi" --size 10000</screen> + </listitem> + + <listitem> + <para> + Add an IDE Controller to the new VM. For example: + </para> + +<screen>VBoxManage storagectl "Windows XP" --name "IDE Controller" + --add ide --controller PIIX4</screen> + </listitem> + + <listitem> + <para> + Set the VDI file you created as the first virtual hard disk + of the new VM. For example: + </para> + +<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller" + --port 0 --device 0 --type hdd --medium "WinXP.vdi"</screen> + </listitem> + + <listitem> + <para> + Attach the ISO file that contains the operating system + installation that you want to install later to the virtual + machine. This is done so that the VM can boot from it. + </para> + +<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller" + --port 0 --device 1 --type dvddrive --medium /full/path/to/iso.iso</screen> + </listitem> + + <listitem> + <para> + Enable the VirtualBox Remote Desktop Extension, the VRDP + server, as follows: + </para> + +<screen>VBoxManage modifyvm "Windows XP" --vrde on</screen> + </listitem> + + <listitem> + <para> + Start the virtual machine using the + <command>VBoxHeadless</command> command: + </para> + +<screen>VBoxHeadless --startvm "Windows XP"</screen> + + <para> + If the configuration steps worked, you should see a + copyright notice. If you are returned to the command line, + then something did not work correctly. + </para> + </listitem> + + <listitem> + <para> + On the client machine, start the RDP viewer and connect to + the server. See <xref linkend="rdp-viewers" /> for details + of how to use various common RDP viewers. + </para> + + <para> + The installation routine of your guest operating system + should be displayed in the RDP viewer. + </para> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="usb-over-rdp"> + + <title>Remote USB</title> + + <para> + As a special feature additional to the VRDP support, + &product-name; also supports remote USB devices over the wire. + That is, an &product-name; guest that runs on one computer can + access the USB devices of the remote computer on which the VRDP + data is being displayed the same way as USB devices that are + connected to the actual host. This enables running of virtual + machines on an &product-name; host that acts as a server, where + a client can connect from elsewhere that needs only a network + adapter and a display capable of running an RDP viewer. When USB + devices are plugged into the client, the remote &product-name; + server can access them. + </para> + + <para> + For these remote USB devices, the same filter rules apply as for + other USB devices. See <xref linkend="settings-usb" />. All you + have to do is specify Remote, or Any, when setting up these + rules. + </para> + + <para> + Accessing remote USB devices is only possible if the RDP client + supports this extension. Some versions of + <command>uttsc</command>, a client tailored for the use with Sun + Ray thin clients, support accessing remote USB devices. RDP + clients for other platforms will be provided in future + &product-name; versions. + </para> + + </sect2> + + <sect2 id="vbox-auth"> + + <title>RDP Authentication</title> + + <para> + For each virtual machine that is remotely accessible using RDP, + you can individually determine if and how client connections are + authenticated. For this, use the <command>VBoxManage + modifyvm</command> command with the + <option>--vrde-auth-type</option> option. See + <xref linkend="vboxmanage-modifyvm" />. The following methods of + authentication are available: + </para> + + <itemizedlist> + + <listitem> + <para> + The <emphasis role="bold">null</emphasis> method means that + there is no authentication at all. Any client can connect to + the VRDP server and thus the virtual machine. This is very + insecure and only to be recommended for private networks. + </para> + </listitem> + + <listitem> + <para> + The <emphasis role="bold">external</emphasis> method + provides external authentication through a special + authentication library. &product-name; ships with two + special authentication libraries: + </para> + + <orderedlist> + + <listitem> + <para> + The default authentication library, + <command>VBoxAuth</command>, authenticates against user + credentials of the hosts. Depending on the host + platform, this means the following: + </para> + + <itemizedlist> + + <listitem> + <para> + On Linux hosts, <command>VBoxAuth.so</command> + authenticates users against the host's PAM system. + </para> + </listitem> + + <listitem> + <para> + On Windows hosts, <command>VBoxAuth.dll</command> + authenticates users against the host's WinLogon + system. + </para> + </listitem> + + <listitem> + <para> + On macOS hosts, <command>VBoxAuth.dylib</command> + authenticates users against the host's directory + service. + </para> + </listitem> + + </itemizedlist> + + <para> + In other words, the external method by default performs + authentication with the user accounts that exist on the + host system. Any user with valid authentication + credentials is accepted. For example, the username does + not have to correspond to the user running the VM. + </para> + </listitem> + + <listitem> + <para> + An additional library called + <command>VBoxAuthSimple</command> performs + authentication against credentials configured in the + <literal>extradata</literal> section of a virtual + machine's XML settings file. This is probably the + simplest way to get authentication that does not depend + on a running and supported guest. The following steps + are required: + </para> + + <orderedlist> + + <listitem> + <para> + Enable <command>VBoxAuthSimple</command> with the + following command: + </para> + +<screen>VBoxManage setproperty vrdeauthlibrary "VBoxAuthSimple"</screen> + </listitem> + + <listitem> + <para> + To enable the library for a particular VM, you must + switch authentication to external, as follows: + </para> + +<screen>VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-auth-type external</screen> + + <para> + Replace <replaceable>VM-name</replaceable> with the + VM name or UUID. + </para> + </listitem> + + <listitem> + <para> + You then need to configure users and passwords by + writing items into the machine's extradata. Since + the XML machine settings file, into whose + <literal>extradata</literal> section the password + needs to be written, is a plain text file, + &product-name; uses hashes to encrypt passwords. The + following command must be used: + </para> + +<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxAuthSimple/users/<replaceable>user</replaceable>" <replaceable>hash</replaceable></screen> + + <para> + Replace <replaceable>VM-name</replaceable> with the + VM name or UUID, <replaceable>user</replaceable> + with the user name who should be allowed to log in + and <replaceable>hash</replaceable> with the + encrypted password. The following command example + obtains the hash value for the password + <literal>secret</literal>: + </para> + +<screen>$ VBoxManage internalcommands passwordhash "secret" +2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen> + + <para> + You then use <command>VBoxManage + setextradata</command> to store this value in the + machine's <literal>extradata</literal> section. + </para> + + <para> + As a combined example, to set the password for the + user <literal>john</literal> and the machine + <literal>My VM</literal> to + <literal>secret</literal>, use this command: + </para> + +<screen>VBoxManage setextradata "My VM" "VBoxAuthSimple/users/john" + 2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen> + </listitem> + + </orderedlist> + </listitem> + + </orderedlist> + </listitem> + + <listitem> + <para> + The <emphasis role="bold">guest</emphasis> authentication + method performs authentication with a special component that + comes with the Guest Additions. As a result, authentication + is not performed on the host, but with the guest user + accounts. + </para> + + <para> + This method is currently still in testing and not yet + supported. + </para> + </listitem> + + </itemizedlist> + + <para> + In addition to the methods described above, you can replace the + default external authentication module with any other module. + For this, &product-name; provides a well-defined interface that + enables you to write your own authentication module. This is + described in detail in the &product-name; Software Development + Kit (SDK) reference. See <xref linkend="VirtualBoxAPI" />. + </para> + + </sect2> + + <sect2 id="vrde-crypt"> + + <title>RDP Encryption</title> + + <para> + RDP features data stream encryption, which is based on the RC4 + symmetric cipher, with keys up to 128-bit. The RC4 keys are + replaced at regular intervals, every 4096 packets. + </para> + + <para> + RDP provides the following different authentication methods: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">RDP 4</emphasis> authentication was + used historically. With RDP 4, the RDP client does not + perform any checks in order to verify the identity of the + server it connects to. Since user credentials can be + obtained using a man in the middle (MITM) attack, RDP4 + authentication is insecure and should generally not be used. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">RDP 5.1</emphasis> authentication + employs a server certificate for which the client possesses + the public key. This way it is guaranteed that the server + possess the corresponding private key. However, as this + hard-coded private key became public some years ago, RDP 5.1 + authentication is also insecure. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">RDP 5.2 or later</emphasis> + authentication uses Enhanced RDP Security, which means that + an external security protocol is used to secure the + connection. RDP 4 and RDP 5.1 use Standard RDP Security. The + VRDP server supports Enhanced RDP Security with TLS protocol + and, as a part of the TLS handshake, sends the server + certificate to the client. + </para> + + <para> + The <literal>Security/Method</literal> VRDE property sets + the desired security method, which is used for a connection. + Valid values are as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Negotiate.</emphasis> Both + Enhanced (TLS) and Standard RDP Security connections are + allowed. The security method is negotiated with the + client. This is the default setting. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">RDP.</emphasis> Only Standard RDP + Security is accepted. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">TLS.</emphasis> Only Enhanced RDP + Security is accepted. The client must support TLS. + </para> + + <para> + The version of OpenSSL used by &product-name; supports + TLS versions 1.0, 1.1, 1.2, and 1.3. + </para> + </listitem> + + </itemizedlist> + + <para> + For example, the following command enables a client to use + either Standard or Enhanced RDP Security connection: + </para> + +<screen>vboxmanage modifyvm <replaceable>VM-name</replaceable> --vrde-property "Security/Method=negotiate"</screen> + + <para> + If the <literal>Security/Method</literal> property is set to + either Negotiate or TLS, the TLS protocol will be + automatically used by the server, if the client supports + TLS. However, in order to use TLS the server must possess + the Server Certificate, the Server Private Key and the + Certificate Authority (CA) Certificate. The following + example shows how to generate a server certificate. + </para> + + <orderedlist> + + <listitem> + <para> + Create a CA self signed certificate. + </para> + +<screen>openssl req -new -x509 -days 365 -extensions v3_ca \ + -keyout ca_key_private.pem -out ca_cert.pem</screen> + </listitem> + + <listitem> + <para> + Generate a server private key and a request for signing. + </para> + +<screen>openssl genrsa -out server_key_private.pem +openssl req -new -key server_key_private.pem -out server_req.pem</screen> + </listitem> + + <listitem> + <para> + Generate the server certificate. + </para> + +<screen>openssl x509 -req -days 365 -in server_req.pem \ + -CA ca_cert.pem -CAkey ca_key_private.pem -set_serial 01 -out server_cert.pem</screen> + </listitem> + + </orderedlist> + + <para> + The server must be configured to access the required files. + For example: + </para> + +<screen>vboxmanage modifyvm <replaceable>VM-name</replaceable> \ + --vrde-property "Security/CACertificate=path/ca_cert.pem"</screen> + +<screen>vboxmanage modifyvm <replaceable>VM-name</replaceable> \ + --vrde-property "Security/ServerCertificate=path/server_cert.pem"</screen> + +<screen>vboxmanage modifyvm <replaceable>VM-name</replaceable> \ + --vrde-property "Security/ServerPrivateKey=path/server_key_private.pem"</screen> + </listitem> + + </itemizedlist> + + <para> + As the client that connects to the server determines what type + of encryption will be used, with <command>rdesktop</command>, + the Linux RDP viewer, use the <option>-4</option> or + <option>-5</option> options. + </para> + + </sect2> + + <sect2 id="vrde-multiconnection"> + + <title>Multiple Connections to the VRDP Server</title> + + <para> + The VRDP server of &product-name; supports multiple simultaneous + connections to the same running VM from different clients. All + connected clients see the same screen output and share a mouse + pointer and keyboard focus. This is similar to several people + using the same computer at the same time, taking turns at the + keyboard. + </para> + + <para> + The following command enables multiple connection mode: + </para> + +<screen>VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-multi-con on</screen> + + </sect2> + + <sect2 id="vrde-multimonitor"> + + <title>Multiple Remote Monitors</title> + + <para> + To access two or more remote VM displays you have to enable the + VRDP multiconnection mode. See + <xref linkend="vrde-multiconnection"/>. + </para> + + <para> + The RDP client can select the virtual monitor number to connect + to using the <literal>domain</literal> login parameter + (<option>-d</option>). If the parameter ends with + <literal>@</literal> followed by a number, &product-name; + interprets this number as the screen index. The primary guest + screen is selected with <literal>@1</literal>, the first + secondary screen is <literal>@2</literal>, and so on. + </para> + + <para> + The Microsoft RDP 6 client does not let you specify a separate + domain name. Instead, enter + <literal><replaceable>domain</replaceable>\<replaceable>username</replaceable></literal> + in the <emphasis role="bold">Username</emphasis> field. For + example, <literal>@2\<replaceable>name</replaceable></literal>. + <replaceable>name</replaceable> must be supplied, and must be + the name used to log in if the VRDP server is set up to require + credentials. If it is not, you may use any text as the username. + </para> + + </sect2> + + <sect2 id="vrde-videochannel"> + + <title>VRDP Video Redirection</title> + + <para> + The VRDP server can redirect video streams from the guest to the + RDP client. Video frames are compressed using the JPEG algorithm + allowing a higher compression ratio than standard RDP bitmap + compression methods. It is possible to increase the compression + ratio by lowering the video quality. + </para> + + <para> + The VRDP server automatically detects video streams in a guest + as frequently updated rectangular areas. As a result, this + method works with any guest operating system without having to + install additional software in the guest. In particular, the + Guest Additions are not required. + </para> + + <para> + On the client side, however, currently only the Windows 7 Remote + Desktop Connection client supports this feature. If a client + does not support video redirection, the VRDP server falls back + to regular bitmap updates. + </para> + + <para> + The following command enables video redirection: + </para> + +<screen>VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-video-channel on</screen> + + <para> + The quality of the video is defined as a value from 10 to 100 + percent, representing a JPEG compression level, where lower + numbers mean lower quality but higher compression. The quality + can be changed using the following command: + </para> + +<screen>VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-video-channel-quality 75</screen> + + </sect2> + + <sect2 id="vrde-customization"> + + <title>VRDP Customization</title> + + <para> + You can disable display output, mouse and keyboard input, audio, + remote USB, or clipboard individually in the VRDP server. + </para> + + <para> + The following commands change the corresponding server settings: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property Client/DisableDisplay=1 +$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property Client/DisableInput=1 +$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property Client/DisableUSB=1 +$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property Client/DisableAudio=1 +$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property Client/DisableClipboard=1 +$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property Client/DisableUpstreamAudio=1</screen> + + <para> + To reenable a feature, use a similar command without the + trailing 1. For example: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property Client/DisableDisplay=</screen> + + </sect2> + + </sect1> + + <sect1 id="teleporting"> + + <title>Teleporting</title> + + <para> + &product-name; supports <emphasis>teleporting</emphasis>. + Teleporting is moving a virtual machine over a network from one + &product-name; host to another, while the virtual machine is + running. This works regardless of the host operating system that + is running on the hosts. You can teleport virtual machines between + Oracle Solaris and macOS hosts, for example. + </para> + + <para> + Teleporting requires that a machine be currently running on one + host, which is called the <emphasis>source</emphasis>. The host to + which the virtual machine will be teleported is called the + <emphasis>target</emphasis>. The machine on the target is then + configured to wait for the source to contact the target. The + machine's running state will then be transferred from the source + to the target with minimal downtime. + </para> + + <para> + Teleporting happens over any TCP/IP network. The source and the + target only need to agree on a TCP/IP port which is specified in + the teleporting settings. + </para> + + <para> + At this time, there are a few prerequisites for this to work, as + follows: + </para> + + <itemizedlist> + + <listitem> + <para> + On the target host, you must configure a virtual machine in + &product-name; with exactly the same hardware settings as the + machine on the source that you want to teleport. This does not + apply to settings which are merely descriptive, such as the VM + name, but obviously for teleporting to work, the target + machine must have the same amount of memory and other hardware + settings. Otherwise teleporting will fail with an error + message. + </para> + </listitem> + + <listitem> + <para> + The two virtual machines on the source and the target must + share the same storage, hard disks as well as floppy disks and + CD/DVD images. This means that they either use the same iSCSI + targets or that the storage resides somewhere on the network + and both hosts have access to it using NFS or SMB/CIFS. + </para> + + <para> + This also means that neither the source nor the target machine + can have any snapshots. + </para> + </listitem> + + </itemizedlist> + + <para> + To configure teleporting, perform the following steps: + </para> + + <orderedlist> + + <listitem> + <para> + On the <emphasis>target</emphasis> host, configure the virtual + machine to wait for a teleport request to arrive when it is + started, instead of actually attempting to start the machine. + This is done with the following <command>VBoxManage</command> + command: + </para> + +<screen>VBoxManage modifyvm <replaceable>targetvmname</replaceable> --teleporter on --teleporter-port <replaceable>port</replaceable></screen> + + <para> + <replaceable>targetvmname</replaceable> is the name of the + virtual machine on the target host and + <replaceable>port</replaceable> is a TCP/IP port number to be + used on both the source and the target hosts. For example, use + 6000. See <xref linkend="vboxmanage-modifyvm" />. + </para> + </listitem> + + <listitem> + <para> + Start the VM on the target host. Instead of running, the VM + shows a progress dialog, indicating that it is waiting for a + teleport request to arrive. + </para> + </listitem> + + <listitem> + <para> + Start the VM on the <emphasis>source</emphasis> host as usual. + When it is running and you want it to be teleported, issue the + following command on the source host: + </para> + +<screen>VBoxManage controlvm <replaceable>sourcevmname</replaceable> teleport --host <replaceable>targethost</replaceable> --port <replaceable>port</replaceable></screen> + + <para> + where <replaceable>sourcevmname</replaceable> is the name of + the virtual machine on the source host, which is the machine + that is currently running. + <replaceable>targethost</replaceable> is the host or IP name + of the target host on which the machine is waiting for the + teleport request, and <replaceable>port</replaceable> must be + the same number as specified in the command on the target + host. See <xref linkend="vboxmanage-controlvm" />. + </para> + </listitem> + + </orderedlist> + + <para> + For testing, you can also teleport machines on the same host. In + that case, use localhost as the hostname on both the source and + the target host. + </para> + + <note> + <para> + In rare cases, if the CPUs of the source and the target are very + different, teleporting can fail with an error message, or the + target may hang. This may happen especially if the VM is running + application software that is highly optimized to run on a + particular CPU without correctly checking that certain CPU + features are actually present. &product-name; filters what CPU + capabilities are presented to the guest operating system. + Advanced users can attempt to restrict these virtual CPU + capabilities with the <command>VBoxManage modifyvm + --cpuid-portability-level</command> command. See + <xref linkend="vboxmanage-modifyvm" />. + </para> + </note> + + </sect1> + + <xi:include href="user_man_VBoxHeadless.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + +</chapter> diff --git a/doc/manual/en_US/user_Glossary.xml b/doc/manual/en_US/user_Glossary.xml new file mode 100644 index 00000000..6d6eb9a1 --- /dev/null +++ b/doc/manual/en_US/user_Glossary.xml @@ -0,0 +1,721 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<glossary id="Glossary"> + <glossdiv> + + <title>A</title> + + <glossentry><glossterm>ACPI</glossterm> + + <glossdef> + + <para> + Advanced Configuration and Power Interface, an industry + specification for BIOS and hardware extensions to configure PC + hardware and perform power management. Windows 2000 and later, + as well as Linux 2.4 and later support ACPI. Windows can only + enable or disable ACPI support at installation time. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>AHCI</glossterm> + + <glossdef> + + <para> + Advanced Host Controller Interface, the interface that + supports SATA devices such as hard disks. See + <xref + linkend="harddiskcontrollers" />. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>AMD-V</glossterm> + + <glossdef> + + <para> + The hardware virtualization features built into modern AMD + processors. See <xref linkend="hwvirt" />. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>API</glossterm> + + <glossdef> + + <para> + Application Programming Interface. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>APIC</glossterm> + + <glossdef> + + <para> + Advanced Programmable Interrupt Controller, a newer version of + the original PC PIC (programmable interrupt controller). Most + modern CPUs contain an on-chip APIC, called a local APIC. Many + systems also contain an I/O APIC (input output APIC) as a + separate chip which provides more than 16 IRQs. Windows 2000 + and later use a different kernel if they detect an I/O APIC + during installation. Therefore, an I/O APIC must not be + removed after installation. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>ATA</glossterm> + + <glossdef> + + <para> + Advanced Technology Attachment, an industry standard for hard + disk interfaces which is synonymous with IDE. See + <xref + linkend="harddiskcontrollers" />. + </para> + + </glossdef> + + </glossentry> + + </glossdiv> + + <glossdiv> + + <title>B</title> + + <glossentry><glossterm>BIOS</glossterm> + + <glossdef> + + <para> + Basic Input/Output System, the firmware built into most + personal computers which is responsible of initializing the + hardware after the computer has been turned on and then + booting an operating system. &product-name; ships with its own + virtual BIOS that runs when a virtual machine is started. + </para> + + </glossdef> + + </glossentry> + + </glossdiv> + + <glossdiv> + + <title>C</title> + + <glossentry><glossterm>COM</glossterm> + + <glossdef> + + <para> + Microsoft Component Object Model, a programming infrastructure + for modular software. COM enables applications to provide + application programming interfaces which can be accessed from + various other programming languages and applications. + &product-name; makes use of COM both internally and externally + to provide a comprehensive API to 3rd party developers. + </para> + + </glossdef> + + </glossentry> + + </glossdiv> + + <glossdiv> + + <title>D</title> + + <glossentry><glossterm>DHCP</glossterm> + + <glossdef> + + <para> + Dynamic Host Configuration Protocol. This enables a networking + device in a network to acquire its IP address and other + networking details automatically, in order to avoid having to + configure all devices in a network with fixed IP addresses. + &product-name; has a built-in DHCP server that delivers an IP + addresses to a virtual machine when networking is configured + to NAT. See <xref + linkend="networkingdetails" />. + </para> + + </glossdef> + + </glossentry> + + </glossdiv> + + <glossdiv> + + <title>E</title> + + <glossentry><glossterm>EFI</glossterm> + + <glossdef> + + <para> + Extensible Firmware Interface, a firmware built into computers + which is designed to replace the aging BIOS. Originally + designed by Intel, most modern operating systems can now boot + on computers which have EFI instead of a BIOS built into them. + See <xref + linkend="efi" />. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>EHCI</glossterm> + + <glossdef> + + <para> + Enhanced Host Controller Interface, the interface that + implements the USB 2.0 standard. + </para> + + </glossdef> + + </glossentry> + + </glossdiv> + + <glossdiv> + + <title>G</title> + + <glossentry><glossterm>GUI</glossterm> + + <glossdef> + + <para> + Graphical User Interface. Commonly used as an antonym to a + "command line interface". In the context of &product-name;, we + sometimes refer to the main graphical + <command>VirtualBox</command> program as the "GUI", to + differentiate it from the <command>VBoxManage</command> + interface. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>GUID</glossterm> + + <glossdef> + + <para> + See UUID. + </para> + + </glossdef> + + </glossentry> + + </glossdiv> + + <glossdiv> + + <title>I</title> + + <glossentry><glossterm>IDE</glossterm> + + <glossdef> + + <para> + Integrated Drive Electronics, an industry standard for hard + disk interfaces. See <xref linkend="harddiskcontrollers" />. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>I/O APIC</glossterm> + + <glossdef> + + <para> + See APIC. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>iSCSI</glossterm> + + <glossdef> + + <para> + Internet SCSI. See <xref linkend="storage-iscsi" />. + </para> + + </glossdef> + + </glossentry> + + </glossdiv> + + <glossdiv> + + <title>M</title> + + <glossentry><glossterm>MAC</glossterm> + + <glossdef> + + <para> + Media Access Control, a part of an Ethernet network card. A + MAC address is a 6-byte number which identifies a network + card. It is typically written in hexadecimal notation where + the bytes are separated by colons, such as + <literal>00:17:3A:5E:CB:08</literal>. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>MSI</glossterm> + + <glossdef> + + <para> + Message Signaled Interrupts, as supported by modern chipsets + such as the ICH9. See <xref linkend="settings-motherboard" />. + As opposed to traditional pin-based interrupts, with MSI, a + small amount of data can accompany the actual interrupt + message. This reduces the amount of hardware pins required and + allows for more interrupts and better performance. + </para> + + </glossdef> + + </glossentry> + + </glossdiv> + + <glossdiv> + + <title>N</title> + + <glossentry><glossterm>NAT</glossterm> + + <glossdef> + + <para> + Network Address Translation. A technique to share networking + interfaces by which an interface modifies the source and/or + target IP addresses of network packets according to specific + rules. Commonly employed by routers and firewalls to shield an + internal network from the Internet, &product-name; can use NAT + to easily share a host's physical networking hardware with its + virtual machines. See <xref + linkend="network_nat" />. + </para> + + </glossdef> + + </glossentry> + + </glossdiv> + + <glossdiv> + + <title>O</title> + + <glossentry><glossterm>OVF</glossterm> + + <glossdef> + + <para> + Open Virtualization Format, a cross-platform industry standard + to exchange virtual appliances between virtualization + products. See <xref linkend="ovf" />. + </para> + + </glossdef> + + </glossentry> + + </glossdiv> + + <glossdiv> + + <title>P</title> + + <glossentry><glossterm>PAE</glossterm> + + <glossdef> + + <para> + Physical Address Extension. This enables access to more than 4 + GB of RAM, even in 32-bit environments. See + <xref linkend="settings-general-advanced" />. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>PIC</glossterm> + + <glossdef> + + <para> + See APIC. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>PXE</glossterm> + + <glossdef> + + <para> + Preboot Execution Environment, an industry standard for + booting PC systems from remote network locations. It includes + DHCP for IP configuration and TFTP for file transfer. Using + UNDI, a hardware independent driver stack for accessing the + network card from bootstrap code is available. + </para> + + </glossdef> + + </glossentry> + + </glossdiv> + + <glossdiv> + + <title>R</title> + + <glossentry><glossterm>RDP</glossterm> + + <glossdef> + + <para> + Remote Desktop Protocol, a protocol developed by Microsoft as + an extension to the ITU T.128 and T.124 video conferencing + protocol. With RDP, a PC system can be controlled from a + remote location using a network connection over which data is + transferred in both directions. Typically graphics updates and + audio are sent from the remote machine and keyboard and mouse + input events are sent from the client. An &product-name; + extension package by Oracle provides VRDP, an enhanced + implementation of the relevant standards which is largely + compatible with Microsoft's RDP implementation. See + <xref linkend="vrde" /> for details. + </para> + + </glossdef> + + </glossentry> + + </glossdiv> + + <glossdiv> + + <title>S</title> + + <glossentry><glossterm>SAS</glossterm> + + <glossdef> + + <para> + Serial Attached SCSI, an industry standard for hard disk + interfaces. See <xref linkend="harddiskcontrollers" />. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>SATA</glossterm> + + <glossdef> + + <para> + Serial ATA, an industry standard for hard disk interfaces. See + <xref linkend="harddiskcontrollers" />. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>SCSI</glossterm> + + <glossdef> + + <para> + Small Computer System Interface. An industry standard for data + transfer between devices, especially for storage. See + <xref + linkend="harddiskcontrollers" />. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>SMP</glossterm> + + <glossdef> + + <para> + Symmetrical Multiprocessing, meaning that the resources of a + computer are shared between several processors. These can + either be several processor chips or, as is more common with + modern hardware, multiple CPU cores in one processor. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>SSD</glossterm> + + <glossdef> + + <para> + Solid-state drive, uses microchips for storing data in a + computer system. Compared to classical hard-disks they are + having no mechanical components like spinning disks. + </para> + + </glossdef> + + </glossentry> + + </glossdiv> + + <glossdiv> + + <title>T</title> + + <glossentry><glossterm>TAR</glossterm> + + <glossdef> + + <para> + A widely used file format for archiving. Originally, this + stood for Tape ARchive and was already supported by very early + UNIX versions for backing up data on tape. The file format is + still widely used today. For example, with OVF archives using + an <filename>.ova</filename> file extension. See + <xref + linkend="ovf" />. + </para> + + </glossdef> + + </glossentry> + + </glossdiv> + + <glossdiv> + + <title>U</title> + + <glossentry><glossterm>UUID</glossterm> + + <glossdef> + + <para> + A Universally Unique Identifier, often also called GUID + (Globally Unique Identifier). A UUID is a string of numbers + and letters which can be computed dynamically and is + guaranteed to be unique. Generally, it is used as a global + handle to identify entities. &product-name; makes use of UUIDs + to identify VMs, Virtual Disk Images (VDI files), and other + entities. + </para> + + </glossdef> + + </glossentry> + + </glossdiv> + + <glossdiv> + + <title>V</title> + + <glossentry><glossterm>VM</glossterm> + + <glossdef> + + <para> + Virtual Machine. A virtual computer that &product-name; + enables you to run on top of your actual hardware. See + <xref + linkend="virtintro" /> for details. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>VMM</glossterm> + + <glossdef> + + <para> + Virtual Machine Manager. The component of &product-name; that + controls VM execution. See + <xref linkend="technical-components" /> for a list of + &product-name; components. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>VRDE</glossterm> + + <glossdef> + + <para> + VirtualBox Remote Desktop Extension. This interface is built + into &product-name; to allow &product-name; extension packages + to supply remote access to virtual machines. An &product-name; + extension package by Oracle provides VRDP support. See + <xref linkend="vrde" />. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>VRDP</glossterm> + + <glossdef> + + <para> + See RDP. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>VT-x</glossterm> + + <glossdef> + + <para> + The hardware virtualization features built into modern Intel + processors. See <xref linkend="hwvirt" />. + </para> + + </glossdef> + + </glossentry> + + </glossdiv> + + <glossdiv> + + <title>X</title> + + <glossentry><glossterm>xHCI</glossterm> + + <glossdef> + + <para> + eXtended Host Controller Interface, the interface that + implements the USB 3.0 standard. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>XML</glossterm> + + <glossdef> + + <para> + The eXtensible Markup Language, a metastandard for all kinds + of textual information. XML only specifies how data in the + document is organized generally and does not prescribe how to + semantically organize content. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>XPCOM</glossterm> + + <glossdef> + + <para> + Mozilla Cross Platform Component Object Model, a programming + infrastructure developed by the Mozilla browser project which + is similar to Microsoft COM and enables applications to + provide a modular programming interface. &product-name; makes + use of XPCOM on Linux both internally and externally to + provide a comprehensive API to third-party developers. + </para> + + </glossdef> + + </glossentry> + + </glossdiv> + +</glossary> diff --git a/doc/manual/en_US/user_GuestAdditions.xml b/doc/manual/en_US/user_GuestAdditions.xml new file mode 100644 index 00000000..f2d4d5d9 --- /dev/null +++ b/doc/manual/en_US/user_GuestAdditions.xml @@ -0,0 +1,2672 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="guestadditions"> + + <title>Guest Additions</title> + + <para> + The previous chapter covered getting started with &product-name; and + installing operating systems in a virtual machine. For any serious + and interactive use, the &product-name; Guest Additions will make + your life much easier by providing closer integration between host + and guest and improving the interactive performance of guest + systems. This chapter describes the Guest Additions in detail. + </para> + + <sect1 id="guestadd-intro"> + + <title>Introduction to Guest Additions</title> + + <para> + As mentioned in <xref linkend="virtintro" />, the Guest Additions + are designed to be installed <emphasis>inside</emphasis> a virtual + machine after the guest operating system has been installed. They + consist of device drivers and system applications that optimize + the guest operating system for better performance and usability. + See <xref linkend="guestossupport" /> for details on what guest + operating systems are fully supported with Guest Additions by + &product-name;. + </para> + + <para> + The &product-name; Guest Additions for all supported guest + operating systems are provided as a single CD-ROM image file which + is called <filename>VBoxGuestAdditions.iso</filename>. This image + file is located in the installation directory of &product-name;. + To install the Guest Additions for a particular VM, you mount this + ISO file in your VM as a virtual CD-ROM and install from there. + </para> + + <para> + The Guest Additions offer the following features: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Mouse pointer integration</emphasis>. To + overcome the limitations for mouse support described in + <xref linkend="keyb_mouse_normal" />, this feature provides + you with seamless mouse support. You will only have one mouse + pointer and pressing the Host key is no longer required to + <emphasis>free</emphasis> the mouse from being captured by the + guest OS. To make this work, a special mouse driver is + installed in the guest that communicates with the physical + mouse driver on your host and moves the guest mouse pointer + accordingly. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Shared folders.</emphasis> These provide + an easy way to exchange files between the host and the guest. + Much like ordinary Windows network shares, you can tell + &product-name; to treat a certain host directory as a shared + folder, and &product-name; will make it available to the guest + operating system as a network share, irrespective of whether + the guest actually has a network. See + <xref linkend="sharedfolders" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Better video support.</emphasis> While + the virtual graphics card which &product-name; emulates for + any guest operating system provides all the basic features, + the custom video drivers that are installed with the Guest + Additions provide you with extra high and non-standard video + modes, as well as accelerated video performance. + </para> + + <para> + In addition, with Windows, Linux, and Oracle Solaris guests, + you can resize the virtual machine's window if the Guest + Additions are installed. The video resolution in the guest + will be automatically adjusted, as if you had manually entered + an arbitrary resolution in the guest's + <emphasis role="bold">Display</emphasis> settings. See + <xref linkend="intro-resize-window" />. + </para> + + <para> + If the Guest Additions are installed, 3D graphics and 2D video + for guest applications can be accelerated. See + <xref linkend="guestadd-video" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Seamless windows.</emphasis> With this + feature, the individual windows that are displayed on the + desktop of the virtual machine can be mapped on the host's + desktop, as if the underlying application was actually running + on the host. See <xref linkend="seamlesswindows" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Generic host/guest communication + channels.</emphasis> The Guest Additions enable you to control + and monitor guest execution. The <emphasis>guest + properties</emphasis> provide a generic string-based mechanism + to exchange data bits between a guest and a host, some of + which have special meanings for controlling and monitoring the + guest. See <xref linkend="guestadd-guestprops" />. + </para> + + <para> + Additionally, applications can be started in a guest from the + host. See <xref linkend="guestadd-guestcontrol" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Time synchronization.</emphasis> With + the Guest Additions installed, &product-name; can ensure that + the guest's system time is better synchronized with that of + the host. + </para> + + <para> + For various reasons, the time in the guest might run at a + slightly different rate than the time on the host. The host + could be receiving updates through NTP and its own time might + not run linearly. A VM could also be paused, which stops the + flow of time in the guest for a shorter or longer period of + time. When the wall clock time between the guest and host only + differs slightly, the time synchronization service attempts to + gradually and smoothly adjust the guest time in small + increments to either catch up or lose time. When the + difference is too great, for example if a VM paused for hours + or restored from saved state, the guest time is changed + immediately, without a gradual adjustment. + </para> + + <para> + The Guest Additions will resynchronize the time regularly. See + <xref linkend="changetimesync" /> for how to configure the + parameters of the time synchronization mechanism. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Shared clipboard.</emphasis> With the + Guest Additions installed, the clipboard of the guest + operating system can optionally be shared with your host + operating system. See <xref linkend="generalsettings" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Automated logins.</emphasis> Also called + credentials passing. See <xref linkend="autologon" />. + </para> + </listitem> + + </itemizedlist> + + <para> + Each version of &product-name;, even minor releases, ship with + their own version of the Guest Additions. While the interfaces + through which the &product-name; core communicates with the Guest + Additions are kept stable so that Guest Additions already + installed in a VM should continue to work when &product-name; is + upgraded on the host, for best results, it is recommended to keep + the Guest Additions at the same version. + </para> + + <para> + The Windows and Linux Guest Additions therefore check + automatically whether they have to be updated. If the host is + running a newer &product-name; version than the Guest Additions, a + notification with further instructions is displayed in the guest. + </para> + + <para> + To disable this update check for the Guest Additions of a given + virtual machine, set the value of its + <literal>/VirtualBox/GuestAdd/CheckHostVersion</literal> guest + property to <literal>0</literal>. See + <xref linkend="guestadd-guestprops" />. + </para> + + </sect1> + + <sect1 id="guestadd-install"> + + <title>Installing and Maintaining Guest Additions</title> + + <para> + Guest Additions are available for virtual machines running + Windows, Linux, Oracle Solaris, or OS/2. The following sections + describe the specifics of each variant in detail. + </para> + + <sect2 id="additions-windows"> + + <title>Guest Additions for Windows</title> + + <para> + The &product-name; Windows Guest Additions are designed to be + installed in a virtual machine running a Windows operating + system. The following versions of Windows guests are supported: + </para> + + <itemizedlist> + + <listitem> + <para> + Microsoft Windows NT 4.0 (any service pack) + </para> + </listitem> + + <listitem> + <para> + Microsoft Windows 2000 (any service pack) + </para> + </listitem> + + <listitem> + <para> + Microsoft Windows XP (any service pack) + </para> + </listitem> + + <listitem> + <para> + Microsoft Windows Server 2003 (any service pack) + </para> + </listitem> + + <listitem> + <para> + Microsoft Windows Server 2008 + </para> + </listitem> + + <listitem> + <para> + Microsoft Windows Vista (all editions) + </para> + </listitem> + + <listitem> + <para> + Microsoft Windows 7 (all editions) + </para> + </listitem> + + <listitem> + <para> + Microsoft Windows 8 (all editions) + </para> + </listitem> + + <listitem> + <para> + Microsoft Windows 10 RTM build 10240 + </para> + </listitem> + + <listitem> + <para> + Microsoft Windows Server 2012 + </para> + </listitem> + + </itemizedlist> + + <sect3 id="mountingadditionsiso"> + + <title>Installing the Windows Guest Additions</title> + + <para> + In the <emphasis role="bold">Devices</emphasis> menu in the + virtual machine's menu bar, &product-name; has a menu item + <emphasis role="bold">Insert Guest Additions CD + Image</emphasis>, which mounts the Guest Additions ISO file + inside your virtual machine. A Windows guest should then + automatically start the Guest Additions installer, which + installs the Guest Additions on your Windows guest. + </para> + + <para> + For other guest operating systems, or if automatic start of + software on a CD is disabled, you need to do a manual start of + the installer. + </para> + + <note> + <para> + For the basic Direct3D acceleration to work in a Windows + guest, you have to install the WDDM video driver available + for Windows Vista or later. + </para> + + <para> + For Windows 8 and later, only the WDDM Direct3D video driver + is available. For basic Direct3D acceleration to work in + Windows XP guests, you have to install the Guest Additions + in Safe Mode. See <xref linkend="KnownIssues" /> for + details. + </para> + </note> + + <para> + If you prefer to mount the Guest Additions manually, you can + perform the following steps: + </para> + + <orderedlist> + + <listitem> + <para> + Start the virtual machine in which you have installed + Windows. + </para> + </listitem> + + <listitem> + <para> + Select <emphasis role="bold">Optical Drives</emphasis> + from the <emphasis role="bold">Devices</emphasis> menu in + the virtual machine's menu bar and then + <emphasis role="bold">Choose/Create a Disk + Image</emphasis>. This displays the Virtual Media Manager, + described in <xref linkend="virtual-media-manager" />. + </para> + </listitem> + + <listitem> + <para> + In the Virtual Media Manager, click + <emphasis role="bold">Add</emphasis> and browse your host + file system for the + <filename>VBoxGuestAdditions.iso</filename> file. + </para> + + <itemizedlist> + + <listitem> + <para> + On a Windows host, this file is in the &product-name; + installation directory, usually in + <filename>C:\Program + files\Oracle\VirtualBox</filename>. + </para> + </listitem> + + <listitem> + <para> + On macOS hosts, this file is in the application bundle + of &product-name;. Right-click on the &product-name; + icon in Finder and choose <emphasis role="bold">Show + Package Contents</emphasis>. The file is located in + the <filename>Contents/MacOS</filename> folder. + </para> + </listitem> + + <listitem> + <para> + On a Linux host, this file is in the + <filename>additions</filename> folder where you + installed &product-name;, usually + <filename>/opt/VirtualBox/</filename>. + </para> + </listitem> + + <listitem> + <para> + On Oracle Solaris hosts, this file is in the + <filename>additions</filename> folder where you + installed &product-name;, usually + <filename>/opt/VirtualBox</filename>. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + In the Virtual Media Manager, select the ISO file and + click the <emphasis role="bold">Add</emphasis> button. + This mounts the ISO file and presents it to your Windows + guest as a CD-ROM. + </para> + </listitem> + + </orderedlist> + + <para> + Unless you have the Autostart feature disabled in your Windows + guest, Windows will now autostart the &product-name; Guest + Additions installation program from the Additions ISO. If the + Autostart feature has been turned off, choose + <filename>VBoxWindowsAdditions.exe</filename> from the CD/DVD + drive inside the guest to start the installer. + </para> + + <para> + The installer will add several device drivers to the Windows + driver database and then invoke the hardware detection wizard. + </para> + + <para> + Depending on your configuration, it might display warnings + that the drivers are not digitally signed. You must confirm + these in order to continue the installation and properly + install the Additions. + </para> + + <para> + After installation, reboot your guest operating system to + activate the Additions. + </para> + + </sect3> + + <sect3 id="additions-windows-updating"> + + <title>Updating the Windows Guest Additions</title> + + <para> + Windows Guest Additions can be updated by running the + installation program again. This replaces the previous + Additions drivers with updated versions. + </para> + + <para> + Alternatively, you can also open the Windows Device Manager + and select <emphasis role="bold">Update Driver...</emphasis> + for the following devices: + </para> + + <itemizedlist> + + <listitem> + <para> + &product-name; Graphics Adapter + </para> + </listitem> + + <listitem> + <para> + &product-name; System Device + </para> + </listitem> + + </itemizedlist> + + <para> + For each, choose the option to provide your own driver, click + <emphasis role="bold">Have Disk</emphasis> and navigate to the + CD-ROM drive with the Guest Additions. + </para> + + </sect3> + + <sect3 id="additions-windows-install-unattended"> + + <title>Unattended Installation of the Windows Guest Additions</title> + + <para> + You can configure unattended installation of the + &product-name; Guest Additions when you create a new VM using + the <emphasis role="bold">Create Virtual Machine</emphasis> + wizard. Select the <emphasis role="bold">Guest + Additions</emphasis> check box on the + <emphasis role="bold">Unattended Guest OS Install</emphasis> + page of the wizard. + </para> + + <para> + Guest Additions are installed automatically, following + completion of the guest OS installation. + </para> + + <simplesect id="additions-windows-install-unattended-certs"> + + <title>Installing Code Signing Certificates</title> + + <para> + To avoid popups when performing an unattended installation + of the &product-name; Guest Additions, the code signing + certificates used to sign the drivers needs to be installed + in the correct certificate stores on the guest operating + system. Failure to do this will cause a typical Windows + installation to display multiple dialogs asking whether you + want to install a particular driver. + </para> + + <note> + <para> + On some legacy Windows versions, such as Windows 2000 and + Windows XP, the user intervention popups mentioned above + are always displayed, even after importing the Oracle + certificates. + </para> + </note> + + <para> + Installing the code signing certificates on a Windows guest + can be done automatically. Use the + <filename>VBoxCertUtil.exe</filename> utility from the + <filename>cert</filename> folder on the Guest Additions + installation CD. + </para> + + <para> + Use the following steps: + </para> + + <orderedlist> + + <listitem> + <para> + Log in as Administrator on the guest. + </para> + </listitem> + + <listitem> + <para> + Mount the &product-name; Guest Additions .ISO. + </para> + </listitem> + + <listitem> + <para> + Open a command line window on the guest and change to + the <filename>cert</filename> folder on the + &product-name; Guest Additions CD. + </para> + </listitem> + + <listitem> + <para> + Run the following command: + </para> + +<screen>VBoxCertUtil.exe add-trusted-publisher vbox*.cer --root vbox*.cer</screen> + + <para> + This command installs the certificates to the + certificate store. When installing the same certificate + more than once, an appropriate error will be displayed. + </para> + </listitem> + + </orderedlist> + + <para> + To allow for completely unattended guest installations, you + can specify a command line parameter to the install + launcher: + </para> + +<screen>VBoxWindowsAdditions.exe /S</screen> + + <para> + This automatically installs the right files and drivers for + the corresponding platform, either 32-bit or 64-bit. + </para> + + <note> + <para> + By default on an unattended installation on a Vista or + Windows 7 guest, there will be the XPDM graphics driver + installed. This graphics driver does not support Windows + Aero / Direct3D on the guest. Instead, the WDDM graphics + driver needs to be installed. To select this driver by + default, add the command line parameter + <literal>/with_wddm</literal> when invoking the Windows + Guest Additions installer. This is only required for Vista + and Windows 7. + </para> + </note> + + <note> + <para> + For Windows Aero to run correctly on a guest, the guest's + VRAM size needs to be configured to at least 128 MB. + </para> + </note> + + <para> + For more options regarding unattended guest installations, + consult the command line help by using the command: + </para> + +<screen>VBoxWindowsAdditions.exe /?</screen> + + </simplesect> + + </sect3> + + <sect3 id="windows-guest-file-extraction"> + + <title>Manual File Extraction</title> + + <para> + If you would like to install the files and drivers manually, + you can extract the files from the Windows Guest Additions + setup as follows: + </para> + +<screen>VBoxWindowsAdditions.exe /extract</screen> + + <para> + To explicitly extract the Windows Guest Additions for another + platform than the current running one, such as 64-bit files on + a 32-bit system, you must use the appropriate platform + installer. Use + <filename>VBoxWindowsAdditions-x86.exe</filename> or + <filename>VBoxWindowsAdditions-amd64.exe</filename> with the + <literal>/extract</literal> parameter. + </para> + + </sect3> + + </sect2> + + <sect2 id="additions-linux"> + + <title>Guest Additions for Linux</title> + + <para> + Like the Windows Guest Additions, the &product-name; Guest + Additions for Linux are a set of device drivers and system + applications which may be installed in the guest operating + system. + </para> + + <para> + The following Linux distributions are officially supported: + </para> + + <itemizedlist> + + <listitem> + <para> + Oracle Linux as of version 5, including UEK kernels + </para> + </listitem> + + <listitem> + <para> + Fedora as of Fedora Core 4 + </para> + </listitem> + + <listitem> + <para> + Red Hat Enterprise Linux as of version 3 + </para> + </listitem> + + <listitem> + <para> + SUSE and openSUSE Linux as of version 9 + </para> + </listitem> + + <listitem> + <para> + Ubuntu as of version 5.10 + </para> + </listitem> + + </itemizedlist> + + <para> + Many other distributions are known to work with the Guest + Additions. + </para> + + <para> + The version of the Linux kernel supplied by default in SUSE and + openSUSE 10.2, Ubuntu 6.10 (all versions) and Ubuntu 6.06 + (server edition) contains a bug which can cause it to crash + during startup when it is run in a virtual machine. The Guest + Additions work in those distributions. + </para> + + <para> + Note that some Linux distributions already come with all or part + of the &product-name; Guest Additions. You may choose to keep + the distribution's version of the Guest Additions but these are + often not up to date and limited in functionality, so we + recommend replacing them with the Guest Additions that come with + &product-name;. The &product-name; Linux Guest Additions + installer tries to detect an existing installation and replace + them but depending on how the distribution integrates the Guest + Additions, this may require some manual interaction. It is + highly recommended to take a snapshot of the virtual machine + before replacing preinstalled Guest Additions. + </para> + + <sect3 id="additions-linux-install"> + + <title>Installing the Linux Guest Additions</title> + + <para> + The &product-name; Guest Additions for Linux are provided on + the same virtual CD-ROM file as the Guest Additions for + Windows. See <xref linkend="mountingadditionsiso"/>. They also + come with an installation program that guides you through the + setup process. However, due to the significant differences + between Linux distributions, installation may be slightly more + complex when compared to Windows. + </para> + + <para> + Installation generally involves the following steps: + </para> + + <orderedlist> + + <listitem> + <para> + Before installing the Guest Additions, you prepare your + guest system for building external kernel modules. This + works as described in + <xref linkend="externalkernelmodules" />, except that this + step must be performed in your Linux + <emphasis>guest</emphasis> instead of on a Linux host + system. + </para> + + <para> + If you suspect that something has gone wrong, check that + your guest is set up correctly and run the following + command as root: + </para> + +<screen>rcvboxadd setup</screen> + </listitem> + + <listitem> + <para> + Insert the <filename>VBoxGuestAdditions.iso</filename> CD + file into your Linux guest's virtual CD-ROM drive, as + described for a Windows guest in + <xref linkend="mountingadditionsiso" />. + </para> + </listitem> + + <listitem> + <para> + Change to the directory where your CD-ROM drive is mounted + and run the following command as root: + </para> + +<screen>sh ./VBoxLinuxAdditions.run</screen> + </listitem> + + </orderedlist> + + </sect3> + + <sect3 id="additions-linux-install-unattended"> + + <title>Unattended Installation of the Linux Guest Additions</title> + + <para> + You can configure unattended installation of the + &product-name; Guest Additions when you create a new VM using + the <emphasis role="bold">Create Virtual Machine</emphasis> + wizard. Select the <emphasis role="bold">Guest + Additions</emphasis> check box on the + <emphasis role="bold">Unattended Guest OS Install</emphasis> + page of the wizard. + </para> + + <para> + Guest Additions are installed automatically, following + completion of the guest OS installation. + </para> + + </sect3> + + <sect3 id="additions-linux-graphics-mouse"> + + <title>Graphics and Mouse Integration</title> + + <para> + In Linux and Oracle Solaris guests, &product-name; graphics + and mouse integration goes through the X Window System. + &product-name; can use the X.Org variant of the system, or + XFree86 version 4.3 which is identical to the first X.Org + release. During the installation process, the X.Org display + server will be set up to use the graphics and mouse drivers + which come with the Guest Additions. + </para> + + <para> + After installing the Guest Additions into a fresh installation + of a supported Linux distribution or Oracle Solaris system, + many unsupported systems will work correctly too, the guest's + graphics mode will change to fit the size of the + &product-name; window on the host when it is resized. You can + also ask the guest system to switch to a particular resolution + by sending a video mode hint using the + <command>VBoxManage</command> tool. + </para> + + <para> + Multiple guest monitors are supported in guests using the + X.Org server version 1.3, which is part of release 7.3 of the + X Window System version 11, or a later version. The layout of + the guest screens can be adjusted as needed using the tools + which come with the guest operating system. + </para> + + <para> + If you want to understand more about the details of how the + X.Org drivers are set up, in particular if you wish to use + them in a setting which our installer does not handle + correctly, see <xref linkend="guestxorgsetup" />. + </para> + + <para> + Starting from &product-name; 7, Linux guest screen resize + functionality for guests running VMSVGA graphics configuration + has been changed. Since then, this functionality consists of a + standalone daemon called VBoxDRMClient and its Desktop + Environment helper counterpart. + </para> + + <para> + VBoxDRMClient runs as a root process and is a bridge between + the host and the guest's vmwgfx driver. This means that + VBoxDRMClient listens to screen resize hints from the host and + forwards them to the vmwgfx driver. This enables guest screen + resize functionality to be available before the user has + performed a graphical login. + </para> + + <para> + In order to perform Desktop Environment specific actions, such + as setting the primary screen in a multimonitor setup, a + Desktop Environment helper is used. Once the user has + performed a graphical login operation, the helper daemon + starts with user session scope and attempts to connect to + VBoxDRMClient using an IPC connection. When VBoxDRMClient has + received a corresponding command from the host, it is + forwarded to the helper daemon over IPC and the action is then + performed. + </para> + + <para> + By default, VBoxDRMClient allows any process to connect to its + IPC socket. This can be restricted by using the following + steps: + </para> + + <orderedlist> + + <listitem> + <para> + The Guest Additions Linux installer creates a + <literal>vboxdrmipc</literal> user group. A corresponding + user needs to be added to this group. + </para> + </listitem> + + <listitem> + <para> + You must set the <literal>DRMIpcRestricted</literal> guest + property, as follows: + </para> + +<screen>VBoxManage guestproperty set "VM name" /VirtualBox/GuestAdd/DRMIpcRestricted 1 \ +--flags RDONLYGUEST</screen> + + <para> + It is important to set only the RDONLYGUEST flag for the + property, so that it cannot be changed from inside the + guest. + </para> + </listitem> + + </orderedlist> + + <note> + <para> + Both steps are required. If one of them is missing, all + processes will have access to the IPC socket. + </para> + </note> + + <para> + Restricted mode can be disabled by unsetting the guest + property, as follows: + </para> + +<screen>VBoxManage guestproperty unset "VM name" /VirtualBox/GuestAdd/DRMIpcRestricted</screen> + + </sect3> + + <sect3 id="additions-linux-updating"> + + <title>Updating the Linux Guest Additions</title> + + <para> + The Guest Additions can simply be updated by going through the + installation procedure again with an updated CD-ROM image. + This will replace the drivers with updated versions. You + should reboot after updating the Guest Additions. + </para> + + </sect3> + + <sect3 id="additions-linux-uninstall"> + + <title>Uninstalling the Linux Guest Additions</title> + + <para> + If you have a version of the Guest Additions installed on your + virtual machine and wish to remove it without installing new + ones, you can do so by inserting the Guest Additions CD image + into the virtual CD-ROM drive as described above. Then run the + installer for the current Guest Additions with the + <literal>uninstall</literal> parameter from the path that the + CD image is mounted on in the guest, as follows: + </para> + +<screen>sh ./VBoxLinuxAdditions.run uninstall</screen> + + <para> + While this will normally work without issues, you may need to + do some manual cleanup of the guest in some cases, especially + of the XFree86Config or xorg.conf file. In particular, if the + Additions version installed or the guest operating system were + very old, or if you made your own changes to the Guest + Additions setup after you installed them. + </para> + + <para> + You can uninstall the Additions as follows: + </para> + +<screen>/opt/VBoxGuestAdditions-<replaceable>version</replaceable>/uninstall.sh</screen> + + <para> + Replace + <filename>/opt/VBoxGuestAdditions-<replaceable>version</replaceable></filename> + with the correct Guest Additions installation directory. + </para> + + </sect3> + + </sect2> + + <sect2 id="additions-solaris"> + + <title>Guest Additions for Oracle Solaris</title> + + <para> + Like the Windows Guest Additions, the &product-name; Guest + Additions for Oracle Solaris take the form of a set of device + drivers and system applications which may be installed in the + guest operating system. + </para> + + <para> + The following Oracle Solaris distributions are officially + supported: + </para> + + <itemizedlist> + + <listitem> + <para> + Oracle Solaris 11, including Oracle Solaris 11 Express + </para> + </listitem> + + <listitem> + <para> + Oracle Solaris 10 4/08 and later + </para> + </listitem> + + </itemizedlist> + + <para> + Other distributions may work if they are based on comparable + software releases. + </para> + + <sect3 id="additions-solaris-install"> + + <title>Installing the Oracle Solaris Guest Additions</title> + + <para> + The &product-name; Guest Additions for Oracle Solaris are + provided on the same ISO CD-ROM as the Additions for Windows + and Linux. They come with an installation program that guides + you through the setup process. + </para> + + <para> + Installation involves the following steps: + </para> + + <orderedlist> + + <listitem> + <para> + Mount the <filename>VBoxGuestAdditions.iso</filename> file + as your Oracle Solaris guest's virtual CD-ROM drive, + exactly the same way as described for a Windows guest in + <xref linkend="mountingadditionsiso" />. + </para> + + <para> + If the CD-ROM drive on the guest does not get mounted, as + seen with some versions of Oracle Solaris 10, run the + following command as root: + </para> + +<screen>svcadm restart volfs</screen> + </listitem> + + <listitem> + <para> + Change to the directory where your CD-ROM drive is mounted + and run the following command as root: + </para> + +<screen>pkgadd -G -d ./VBoxSolarisAdditions.pkg</screen> + </listitem> + + <listitem> + <para> + Choose <emphasis role="bold">1</emphasis> and confirm + installation of the Guest Additions package. After the + installation is complete, log out and log in to X server + on your guest, to activate the X11 Guest Additions. + </para> + </listitem> + + </orderedlist> + + </sect3> + + <sect3 id="additions-solaris-install-unattended"> + + <title>Unattended Installation of the Oracle Solaris Guest Additions</title> + + <para> + You can configure unattended installation of the + &product-name; Guest Additions when you create a new VM using + the <emphasis role="bold">Create Virtual Machine</emphasis> + wizard. Select the <emphasis role="bold">Guest + Additions</emphasis> check box on the + <emphasis role="bold">Unattended Guest OS Install</emphasis> + page of the wizard. + </para> + + <para> + Guest Additions are installed automatically, following + completion of the guest OS installation. + </para> + + </sect3> + + <sect3 id="additions-solaris-uninstall"> + + <title>Uninstalling the Oracle Solaris Guest Additions</title> + + <para> + The Oracle Solaris Guest Additions can be safely removed by + removing the package from the guest. Open a root terminal + session and run the following command: + </para> + +<screen>pkgrm SUNWvboxguest</screen> + + </sect3> + + <sect3 id="additions-solaris-updating"> + + <title>Updating the Oracle Solaris Guest Additions</title> + + <para> + The Guest Additions should be updated by first uninstalling + the existing Guest Additions and then installing the new ones. + Attempting to install new Guest Additions without removing the + existing ones is not possible. + </para> + + </sect3> + + </sect2> + + <sect2 id="additions-os2"> + + <title>Guest Additions for OS/2</title> + + <para> + &product-name; also ships with a set of drivers that improve + running OS/2 in a virtual machine. Due to restrictions of OS/2 + itself, this variant of the Guest Additions has a limited + feature set. See <xref linkend="KnownIssues" /> for details. + </para> + + <para> + The OS/2 Guest Additions are provided on the same ISO CD-ROM as + those for the other platforms. Mount the ISO in OS/2 as + described previously. The OS/2 Guest Additions are located in + the directory <filename>\OS2</filename>. + </para> + + <para> + We do not provide an automatic installer at this time. See the + <filename>readme.txt</filename> file in the CD-ROM directory, + which describes how to install the OS/2 Guest Additions + manually. + </para> + + </sect2> + + </sect1> + + <sect1 id="sharedfolders"> + + <title>Shared Folders</title> + + <para> + With the <emphasis>shared folders</emphasis> feature of + &product-name;, you can access files of your host system from + within the guest system. This is similar to how you would use + network shares in Windows networks, except that shared folders do + not require networking, only the Guest Additions. Shared folders + are supported with Windows 2000 or later, Linux, and Oracle + Solaris guests. &product-name; includes experimental support for + Mac OS X and OS/2 guests. + </para> + + <para> + Shared folders physically reside on the <emphasis>host</emphasis> + and are then shared with the guest, which uses a special file + system driver in the Guest Additions to talk to the host. For + Windows guests, shared folders are implemented as a pseudo-network + redirector. For Linux and Oracle Solaris guests, the Guest + Additions provide a virtual file system. + </para> + + <para> + To share a host folder with a virtual machine in &product-name;, + you must specify the path of the folder and choose a + <emphasis>share name</emphasis> that the guest can use to access + the shared folder. This happens on the host. In the guest you can + then use the share name to connect to it and access files. + </para> + + <para> + There are several ways in which shared folders can be set up for a + virtual machine: + </para> + + <itemizedlist> + + <listitem> + <para> + In the window of a running VM, you select + <emphasis role="bold">Shared Folders</emphasis> from the + <emphasis role="bold">Devices</emphasis> menu, or click on the + folder icon on the status bar in the bottom right corner. + </para> + </listitem> + + <listitem> + <para> + If a VM is not currently running, you can configure shared + folders in the virtual machine's + <emphasis role="bold">Settings</emphasis> window. + </para> + </listitem> + + <listitem> + <para> + From the command line, you can create shared folders using + <command>VBoxManage</command>, as follows: + </para> + +<screen>VBoxManage sharedfolder add "VM name" --name "sharename" --hostpath "C:\test"</screen> + + <para> + See <xref linkend="vboxmanage-sharedfolder" />. + </para> + </listitem> + + </itemizedlist> + + <para> + There are two types of shares: + </para> + + <itemizedlist> + + <listitem> + <para> + Permanent shares, that are saved with the VM settings. + </para> + </listitem> + + <listitem> + <para> + Transient shares, that are added at runtime and disappear when + the VM is powered off. These can be created using a check box + in &vbox-mgr;, or by using the <option>--transient</option> + option of the <command>VBoxManage sharedfolder add</command> + command. + </para> + </listitem> + + </itemizedlist> + + <para> + Shared folders can either be read-write or read-only. This means + that the guest is either allowed to both read and write, or just + read files on the host. By default, shared folders are read-write. + Read-only folders can be created using a check box in the + &vbox-mgr;, or with the <option>--readonly</option> option of the + <command>VBoxManage sharedfolder add</command> command. + </para> + + <para> + &product-name; shared folders also support symbolic links, also + called <emphasis>symlinks</emphasis>, under the following + conditions: + </para> + + <itemizedlist> + + <listitem> + <para> + The host operating system must support symlinks. For example, + a macOS, Linux, or Oracle Solaris host is required. + </para> + </listitem> + + <listitem> + <para> + Currently only Linux and Oracle Solaris Guest Additions + support symlinks. + </para> + </listitem> + + <listitem> + <para> + For security reasons the guest OS is not allowed to create + symlinks by default. If you trust the guest OS to not abuse + the functionality, you can enable creation of symlinks for a + shared folder as follows: + </para> + +<screen>VBoxManage setextradata "VM name" VBoxInternal2/SharedFoldersEnableSymlinksCreate/<replaceable>sharename</replaceable> 1</screen> + </listitem> + + </itemizedlist> + + <sect2 id="sf_mount_manual"> + + <title>Manual Mounting</title> + + <para> + You can mount the shared folder from inside a VM, in the same + way as you would mount an ordinary network share: + </para> + + <itemizedlist> + + <listitem> + <para> + In a Windows guest, shared folders are browseable and + therefore visible in Windows Explorer. To attach the host's + shared folder to your Windows guest, open Windows Explorer + and look for the folder in <emphasis role="bold">My + Networking Places</emphasis>, <emphasis role="bold">Entire + Network</emphasis>, <emphasis role="bold">&product-name; + Shared Folders</emphasis>. By right-clicking on a shared + folder and selecting <emphasis role="bold">Map Network + Drive</emphasis> from the menu that pops up, you can assign + a drive letter to that shared folder. + </para> + + <para> + Alternatively, on the Windows command line, use the + following command: + </para> + +<screen>net use x: \\vboxsvr\sharename</screen> + + <para> + While <literal>vboxsvr</literal> is a fixed name, note that + <literal>vboxsrv</literal> would also work, replace + <replaceable>x:</replaceable> with the drive letter that you + want to use for the share, and + <replaceable>sharename</replaceable> with the share name + specified with <command>VBoxManage</command>. + </para> + </listitem> + + <listitem> + <para> + In a Linux guest, use the following command: + </para> + +<screen>mount -t vboxsf [-o OPTIONS] sharename mountpoint</screen> + + <para> + To mount a shared folder during boot, add the following + entry to <filename>/etc/fstab</filename>: + </para> + +<screen>sharename mountpoint vboxsf defaults 0 0</screen> + </listitem> + + <listitem> + <para> + In a Oracle Solaris guest, use the following command: + </para> + +<screen>mount -F vboxfs [-o OPTIONS] sharename mountpoint</screen> + + <para> + Replace <replaceable>sharename</replaceable>, use a + lowercase string, with the share name specified with + <command>VBoxManage</command> or &vbox-mgr;. Replace + <replaceable>mountpoint</replaceable> with the path where + you want the share to be mounted on the guest, such as + <filename>/mnt/share</filename>. The usual mount rules + apply. For example, create this directory first if it does + not exist yet. + </para> + + <para> + Here is an example of mounting the shared folder for the + user jack on Oracle Solaris: + </para> + +<screen>$ id +uid=5000(jack) gid=1(other) +$ mkdir /export/home/jack/mount +$ pfexec mount -F vboxfs -o uid=5000,gid=1 jackshare /export/home/jack/mount +$ cd ~/mount +$ ls +sharedfile1.mp3 sharedfile2.txt +$</screen> + + <para> + Beyond the standard options supplied by the + <command>mount</command> command, the following are + available: + </para> + +<screen>iocharset CHARSET</screen> + + <para> + This option sets the character set used for I/O operations. + Note that on Linux guests, if the + <literal>iocharset</literal> option is not specified, then + the Guest Additions driver will attempt to use the character + set specified by the CONFIG_NLS_DEFAULT kernel option. If + this option is not set either, then UTF-8 is used. + </para> + +<screen>convertcp CHARSET</screen> + + <para> + This option specifies the character set used for the shared + folder name. This is UTF-8 by default. + </para> + + <para> + The generic mount options, documented in the + <command>mount</command> manual page, apply also. Especially + useful are the options <literal>uid</literal>, + <literal>gid</literal> and <literal>mode</literal>, as they + can allow access by normal users in read/write mode, + depending on the settings, even if root has mounted the + filesystem. + </para> + </listitem> + + <listitem> + <para> + In an OS/2 guest, use the <command>VBoxControl</command> + command to manage shared folders. For example: + </para> + +<screen>VBoxControl sharedfolder use D: MyShareName +VBoxControl sharedfolder unuse D: +VBoxControl sharedfolder list</screen> + + <para> + As with Windows guests, shared folders can also be accessed + via UNC using <filename>\\VBoxSF\</filename>, + <filename>\\VBoxSvr\</filename> or + <filename>\\VBoxSrv\</filename> as the server name and the + shared folder name as <replaceable>sharename</replaceable>. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="sf_mount_auto"> + + <title>Automatic Mounting</title> + + <para> + &product-name; provides the option to mount shared folders + automatically. When automatic mounting is enabled for a shared + folder, the Guest Additions service will mount it for you + automatically. For Windows or OS/2, a preferred drive letter can + also be specified. For Linux or Oracle Solaris, a mount point + directory can also be specified. + </para> + + <para> + If a drive letter or mount point is not specified, or is in use + already, an alternative location is found by the Guest Additions + service. The service searches for an alternative location + depending on the guest OS, as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Windows and OS/2 guests.</emphasis> + Search for a free drive letter, starting at + <filename>Z:</filename>. If all drive letters are assigned, + the folder is not mounted. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Linux and Oracle Solaris + guests.</emphasis> Folders are mounted under the + <filename>/media</filename> directory. The folder name is + normalized (no spaces, slashes or colons) and is prefixed + with <filename>sf_</filename>. + </para> + + <para> + For example, if you have a shared folder called + <filename>myfiles</filename>, it will appear as + <filename>/media/sf_myfiles</filename> in the guest. + </para> + + <para> + The guest properties + <literal>/VirtualBox/GuestAdd/SharedFolders/MountDir</literal> + and the more generic + <literal>/VirtualBox/GuestAdd/SharedFolders/MountPrefix</literal> + can be used to override the automatic mount directory and + prefix. See <xref linkend="guestadd-guestprops" />. + </para> + </listitem> + + </itemizedlist> + + <para> + Access to an automatically mounted shared folder is granted to + everyone in a Windows guest, including the guest user. For Linux + and Oracle Solaris guests, access is restricted to members of + the group <literal>vboxsf</literal> and the + <literal>root</literal> user. + </para> + + </sect2> + + </sect1> + + <sect1 id="guestadd-dnd"> + + <title>Drag and Drop</title> + + <para> + &product-name; enables you to drag and drop content from the host + to the guest, and vice versa. For this to work the latest version + of the Guest Additions must be installed on the guest. + </para> + + <para> + Drag and drop transparently allows copying or opening files, + directories, and even certain clipboard formats from one end to + the other. For example, from the host to the guest or from the + guest to the host. You then can perform drag and drop operations + between the host and a VM, as it would be a native drag and drop + operation on the host OS. + </para> + + <para> + At the moment drag and drop is implemented for Windows-based and + X-Windows-based systems, both on the host and guest side. As + X-Windows supports many different drag and drop protocols only the + most common one, XDND, is supported for now. Applications using + other protocols, such as Motif or OffiX, will not be recognized by + &product-name;. + </para> + + <para> + In the context of using drag and drop, the origin of the data is + called the <emphasis>source</emphasis>. That is, where the actual + data comes from and is specified. The + <emphasis>destination</emphasis> specifies where the data from the + source should go to. Transferring data from the source to the + destination can be done in various ways, such as copying, moving, + or linking. + </para> + + <note> + <para> + At the moment only copying of data is supported. Moving or + linking is not yet implemented. + </para> + </note> + + <para> + When transferring data from the host to the guest OS, the host in + this case is the source, whereas the guest OS is the destination. + However, when transferring data from the guest OS to the host, the + guest OS this time became the source and the host is the + destination. + </para> + + <para> + For security reasons drag and drop can be configured at runtime on + a per-VM basis either using the <emphasis role="bold">Drag and + Drop</emphasis> menu item in the + <emphasis role="bold">Devices</emphasis> menu of the virtual + machine, as shown below, or the <command>VBoxManage</command> + command. + </para> + + <figure id="fig-drag-drop-options"> + <title>Drag and Drop Menu Options</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/dnd-modes.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The following drag and drop modes are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Disabled.</emphasis> Disables the drag + and drop feature entirely. This is the default when creating a + new VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Host To Guest.</emphasis> Enables drag + and drop operations from the host to the guest only. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Guest To Host.</emphasis> Enables drag + and drop operations from the guest to the host only. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Bidirectional.</emphasis> Enables drag + and drop operations in both directions: from the host to the + guest, and from the guest to the host. + </para> + </listitem> + + </itemizedlist> + + <note> + <para> + Drag and drop support depends on the frontend being used. At the + moment, only the &vbox-mgr; frontend provides this + functionality. + </para> + </note> + + <para> + To use the <command>VBoxManage</command> command to control the + current drag and drop mode, see <xref linkend="vboxmanage" />. The + <command>modifyvm</command> and <command>controlvm</command> + commands enable setting of a VM's current drag and drop mode from + the command line. + </para> + + <sect2 id="guestadd-dnd-formats"> + + <title>Supported Formats</title> + + <para> + As &product-name; can run on a variety of host operating systems + and also supports a wide range of guests, certain data formats + must be translated after transfer. This is so that the + destination operating system, which receives the data, is able + to handle them in an appropriate manner. + </para> + + <note> + <para> + When dragging files no data conversion is done in any way. For + example, when transferring a file from a Linux guest to a + Windows host the Linux-specific line endings are not converted + to Windows line endings. + </para> + </note> + + <para> + The following formats are handled by the &product-name; drag and + drop service: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Plain text:</emphasis> From + applications such as text editors, internet browsers and + terminal windows. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Files:</emphasis> From file managers + such as Windows Explorer, Nautilus, and Finder. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Directories:</emphasis> For + directories, the same formats apply as for files. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="guestadd-dnd-limitations"> + + <title>Known Limitations</title> + + <para> + The following limitations are known for drag and drop: + </para> + + <para> + On Windows hosts, dragging and dropping content between + UAC-elevated (User Account Control) programs and + non-UAC-elevated programs is not allowed. If you start + &product-name; with Administrator privileges then drag and drop + will not work with Windows Explorer, which runs with regular + user privileges by default. + </para> + + <para> + On Linux hosts and guests, programs can query for drag and drop + data while the drag operation is still in progress. For example, + on LXDE using the PCManFM file manager. This currently is not + supported. As a workaround, a different file manager, such as + Nautilus, can be used instead. + </para> + + </sect2> + + </sect1> + + <sect1 id="guestadd-video"> + + <title>Hardware-Accelerated Graphics</title> + + <sect2 id="guestadd-3d"> + + <title>Hardware 3D Acceleration (OpenGL and Direct3D 8/9)</title> + + <para> + The &product-name; Guest Additions contain experimental hardware + 3D support for Windows, Linux, and Oracle Solaris guests. + </para> + + <para> + With this feature, if an application inside your virtual machine + uses 3D features through the OpenGL or Direct3D 8/9 programming + interfaces, instead of emulating them in software, which would + be slow, &product-name; will attempt to use your host's 3D + hardware. This works for all supported host platforms, provided + that your host operating system can make use of your accelerated + 3D hardware in the first place. + </para> + + <para> + The 3D acceleration feature currently has the following + preconditions: + </para> + + <itemizedlist> + + <listitem> + <para> + It is only available for certain Windows, Linux, and Oracle + Solaris guests. In particular: + </para> + + <itemizedlist> + + <listitem> + <para> + 3D acceleration with Windows guests requires Windows + 2000 or later. Apart from on Windows 2000 guests, both + OpenGL and Direct3D 8/9 are supported on an experimental + basis. + </para> + </listitem> + + <listitem> + <para> + OpenGL on Linux requires kernel 2.6.27 or later, as well + as X.org server version 1.5 or later. Ubuntu 10.10 and + Fedora 14 have been tested and confirmed as working. + </para> + </listitem> + + <listitem> + <para> + OpenGL on Oracle Solaris guests requires X.org server + version 1.5 or later. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + The Guest Additions must be installed. + </para> + + <note> + <para> + For the basic Direct3D acceleration to work in a Windows + Guest, &product-name; needs to replace Windows system + files in the virtual machine. As a result, the Guest + Additions installation program offers Direct3D + acceleration as an option that must be explicitly enabled. + Also, you must install the Guest Additions in Safe Mode. + This does <emphasis>not</emphasis> apply to the WDDM + Direct3D video driver available for Windows Vista and + later. See <xref linkend="KnownIssues" /> for details. + </para> + </note> + </listitem> + + <listitem> + <para> + Because 3D support is still experimental at this time, it is + disabled by default and must be <emphasis>manually + enabled</emphasis> in the VM settings. See + <xref linkend="settings-display" />. + </para> + + <note> + <para> + Untrusted guest systems should not be allowed to use the + 3D acceleration features of &product-name;, just as + untrusted host software should not be allowed to use 3D + acceleration. Drivers for 3D hardware are generally too + complex to be made properly secure and any software which + is allowed to access them may be able to compromise the + operating system running them. In addition, enabling 3D + acceleration gives the guest direct access to a large body + of additional program code in the &product-name; host + process which it might conceivably be able to use to crash + the virtual machine. + </para> + </note> + </listitem> + + </itemizedlist> + + <para> + To enable Aero theme support, the &product-name; WDDM video + driver must be installed, which is available with the Guest + Additions installation. The WDDM driver is not installed by + default for Vista and Windows 7 guests and must be + <emphasis>manually selected</emphasis> in the Guest Additions + installer by clicking <emphasis role="bold">No</emphasis> in the + <emphasis role="bold">Would You Like to Install Basic Direct3D + Support</emphasis> dialog displayed when the Direct3D feature is + selected. + </para> + + <para> + The Aero theme is not enabled by default on Windows. See your + Windows platform documentation for details of how to enable the + Aero theme. + </para> + + <para> + Technically, &product-name; implements 3D acceleration by + installing an additional hardware 3D driver inside the guest + when the Guest Additions are installed. This driver acts as a + hardware 3D driver and reports to the guest operating system + that the virtual hardware is capable of 3D hardware + acceleration. When an application in the guest then requests + hardware acceleration through the OpenGL or Direct3D programming + interfaces, these are sent to the host through a special + communication tunnel implemented by &product-name;. The + <emphasis>host</emphasis> then performs the requested 3D + operation using the host's programming interfaces. + </para> + + </sect2> + + <sect2 id="guestadd-2d"> + + <title>Hardware 2D Video Acceleration for Windows Guests</title> + + <para> + The &product-name; Guest Additions contain experimental hardware + 2D video acceleration support for Windows guests. + </para> + + <para> + With this feature, if an application such as a video player + inside your Windows VM uses 2D video overlays to play a movie + clip, then &product-name; will attempt to use your host's video + acceleration hardware instead of performing overlay stretching + and color conversion in software, which would be slow. This + currently works for Windows, Linux and macOS host platforms, + provided that your host operating system can make use of 2D + video acceleration in the first place. + </para> + + <para> + Hardware 2D video acceleration currently has the following + preconditions: + </para> + + <itemizedlist> + + <listitem> + <para> + Only available for Windows guests, running Windows XP or + later. + </para> + </listitem> + + <listitem> + <para> + Guest Additions must be installed. + </para> + </listitem> + + <listitem> + <para> + Because 2D support is still experimental at this time, it is + disabled by default and must be <emphasis>manually + enabled</emphasis> in the VM settings. See + <xref linkend="settings-display" />. + </para> + </listitem> + + </itemizedlist> + + <para> + Technically, &product-name; implements this by exposing video + overlay DirectDraw capabilities in the Guest Additions video + driver. The driver sends all overlay commands to the host + through a special communication tunnel implemented by + &product-name;. On the host side, OpenGL is then used to + implement color space transformation and scaling. + </para> + + </sect2> + + </sect1> + + <sect1 id="seamlesswindows"> + + <title>Seamless Windows</title> + + <para> + With the <emphasis>seamless windows</emphasis> feature of + &product-name;, you can have the windows that are displayed within + a virtual machine appear side by side next to the windows of your + host. This feature is supported for the following guest operating + systems, provided that the Guest Additions are installed: + </para> + + <itemizedlist> + + <listitem> + <para> + Windows guests. + </para> + </listitem> + + <listitem> + <para> + Supported Linux or Oracle Solaris guests running the X Window + System. + </para> + </listitem> + + </itemizedlist> + + <para> + After seamless windows are enabled, &product-name; suppresses the + display of the desktop background of your guest, allowing you to + run the windows of your guest operating system seamlessly next to + the windows of your host. + </para> + + <figure id="fig-seamless-windows"> + <title>Seamless Windows on a Host Desktop</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/seamless.png" width="14cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + To enable seamless mode, after starting the virtual machine, press + the <emphasis role="bold">Host key + L</emphasis>. The Host key is + normally the right control key. This will enlarge the size of the + VM's display to the size of your host screen and mask out the + guest operating system's background. To disable seamless windows + and go back to the normal VM display, press the Host key + L + again. + </para> + + </sect1> + + <sect1 id="guestadd-guestprops"> + + <title>Guest Properties</title> + + <para> + &product-name; enables requests of some properties from a running + guest, provided that the &product-name; Guest Additions are + installed and the VM is running. This provides the following + advantages: + </para> + + <itemizedlist> + + <listitem> + <para> + A number of predefined VM characteristics are automatically + maintained by &product-name; and can be retrieved on the host. + For example, to monitor VM performance and statistics. + </para> + </listitem> + + <listitem> + <para> + Arbitrary string data can be exchanged between guest and host. + This works in both directions. + </para> + </listitem> + + </itemizedlist> + + <para> + To accomplish this, &product-name; establishes a private + communication channel between the &product-name; Guest Additions + and the host, and software on both sides can use this channel to + exchange string data for arbitrary purposes. Guest properties are + simply string keys to which a value is attached. They can be set, + or written to, by either the host and the guest. They can also be + read from both sides. + </para> + + <para> + In addition to establishing the general mechanism of reading and + writing values, a set of predefined guest properties is + automatically maintained by the &product-name; Guest Additions to + allow for retrieving interesting guest data such as the guest's + exact operating system and service pack level, the installed + version of the Guest Additions, users that are currently logged + into the guest OS, network statistics and more. These predefined + properties are all prefixed with <literal>/VirtualBox/</literal> + and organized into a hierarchical tree of keys. + </para> + + <para> + Some of this runtime information is shown when you select + <emphasis role="bold">Session Information Dialog</emphasis> from a + virtual machine's <emphasis role="bold">Machine</emphasis> menu. + </para> + + <para> + A more flexible way to use this channel is with the + <command>VBoxManage guestproperty</command> command. See + <xref linkend="vboxmanage-guestproperty" />. For example, to have + <emphasis>all</emphasis> the available guest properties for a + given running VM listed with their respective values, use this + command: + </para> + +<screen>$ VBoxManage guestproperty enumerate "Windows Vista III" +VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable> +Copyright (C) 2005-2023 Oracle and/or its affiliates + +Name: /VirtualBox/GuestInfo/OS/Product, value: Windows Vista Business Edition, + timestamp: 1229098278843087000, flags: +Name: /VirtualBox/GuestInfo/OS/Release, value: 6.0.6001, + timestamp: 1229098278950553000, flags: +Name: /VirtualBox/GuestInfo/OS/ServicePack, value: 1, + timestamp: 1229098279122627000, flags: +Name: /VirtualBox/GuestAdd/InstallDir, + value: C:/Program Files/Oracle/VirtualBox + Guest Additions, timestamp: 1229098279269739000, flags: +Name: /VirtualBox/GuestAdd/Revision, value: 40720, + timestamp: 1229098279345664000, flags: +Name: /VirtualBox/GuestAdd/Version, value: <replaceable>version-number</replaceable>, + timestamp: 1229098279479515000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxControl.exe, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279651731000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxHook.dll, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279804835000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxDisp.dll, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279880611000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxMRXNP.dll, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279882618000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxService.exe, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279883195000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxTray.exe, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279885027000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxGuest.sys, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279886838000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxMouse.sys, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279890600000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxSF.sys, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279893056000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxVideo.sys, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279895767000, flags: +Name: /VirtualBox/GuestInfo/OS/LoggedInUsers, value: 1, + timestamp: 1229099826317660000, flags: +Name: /VirtualBox/GuestInfo/OS/NoLoggedInUsers, value: false, + timestamp: 1229098455580553000, flags: +Name: /VirtualBox/GuestInfo/Net/Count, value: 1, + timestamp: 1229099826299785000, flags: +Name: /VirtualBox/HostInfo/GUI/LanguageID, value: C, + timestamp: 1229098151272771000, flags: +Name: /VirtualBox/GuestInfo/Net/0/V4/IP, value: 192.168.2.102, + timestamp: 1229099826300088000, flags: +Name: /VirtualBox/GuestInfo/Net/0/V4/Broadcast, value: 255.255.255.255, + timestamp: 1229099826300220000, flags: +Name: /VirtualBox/GuestInfo/Net/0/V4/Netmask, value: 255.255.255.0, + timestamp: 1229099826300350000, flags: +Name: /VirtualBox/GuestInfo/Net/0/Status, value: Up, + timestamp: 1229099826300524000, flags: +Name: /VirtualBox/GuestInfo/OS/LoggedInUsersList, value: username, + timestamp: 1229099826317386000, flags:</screen> + + <para> + To query the value of a single property, use the + <command>get</command> subcommand as follows: + </para> + +<screen>$ VBoxManage guestproperty get "Windows Vista III" "/VirtualBox/GuestInfo/OS/Product" +VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable> +Copyright (C) 2005-2023 Oracle and/or its affiliates + +Value: Windows Vista Business Edition</screen> + + <para> + To add or change guest properties from the guest, use the tool + <command>VBoxControl</command>. This tool is included in the Guest + Additions. When started from a Linux guest, this tool requires + root privileges for security reasons. + </para> + +<screen>$ sudo VBoxControl guestproperty enumerate +VirtualBox Guest Additions Command Line Management Interface Version <replaceable>version-number</replaceable> +Copyright (C) 2005-2023 Oracle and/or its affiliates + +Name: /VirtualBox/GuestInfo/OS/Release, value: 2.6.28-18-generic, + timestamp: 1265813265835667000, flags: <NULL> +Name: /VirtualBox/GuestInfo/OS/Version, value: #59-Ubuntu SMP Thu Jan 28 01:23:03 UTC 2010, + timestamp: 1265813265836305000, flags: <NULL> + ...</screen> + + <para> + For more complex needs, you can use the &product-name; programming + interfaces. See <xref linkend="VirtualBoxAPI" />. + </para> + + <sect2 id="guestadd-guestprops-waits"> + + <title>Using Guest Properties to Wait on VM Events</title> + + <para> + The properties <literal>/VirtualBox/HostInfo/VBoxVer</literal>, + <literal>/VirtualBox/HostInfo/VBoxVerExt</literal> or + <literal>/VirtualBox/HostInfo/VBoxRev</literal> can be waited on + to detect that the VM state was restored from saved state or + snapshot: + </para> + +<screen>$ VBoxControl guestproperty wait /VirtualBox/HostInfo/VBoxVer</screen> + + <para> + Similarly the + <literal>/VirtualBox/HostInfo/ResumeCounter</literal> can be + used to detect that a VM was resumed from the paused state or + saved state. + </para> + + </sect2> + + </sect1> + + <sect1 id="guestadd-gc-file-manager"> + + <title>Guest Control File Manager</title> + + <para> + The Guest Control File Manager is a feature of the Guest Additions + that enables easy copying and moving of files between a guest and + the host system. Other file management operations provide support + to create new folders and to rename or delete files. + </para> + + <para> + This feature is useful when the VM window of a guest is not + visible. For example, when the guest is running in headless mode. + </para> + + <note> + <para> + To use the Guest Control File Manager, the guest must be + running. For powered-off guests, it is disabled automatically. + </para> + </note> + + <figure id="fig-guest-control-fm"> + <title>Guest Control File Manager</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/guest-fm.png" + width="12cm" /> + </imageobject> + </mediaobject> + + </figure> + + <para> + The Guest Control File Manager works by mounting the host file + system. Guest users must authenticate and create a guest session + before they can transfer files. + </para> + + <sect2 id="guestadd-gc-file-manager-using"> + + <title>Using the Guest Control File Manager</title> + + <para> + The following steps describe how to use the Guest Control File + Manager. + </para> + + <orderedlist> + + <listitem> + <para> + Open the Guest Control File Manager. Do either of the + following: + </para> + + <itemizedlist> + + <listitem> + <para> + In the guest VM, select + <emphasis role="bold">Machine</emphasis>, + <emphasis role="bold">File Manager</emphasis>. + </para> + </listitem> + + <listitem> + <para> + In &vbox-mgr;, click on the machine name. Click + <emphasis role="bold">File Manager</emphasis> in the + machine tools menu for the VM. + </para> + </listitem> + + </itemizedlist> + + <para> + The left pane shows the files on the host system. + </para> + </listitem> + + <listitem> + <para> + Create a guest session. + </para> + + <para> + At the bottom of the Guest Control File Manager, enter + authentication credentials for a user on the guest system. + </para> + + <para> + Click <emphasis role="bold">Create Session</emphasis>. + </para> + + <para> + The contents of the guest VM file system appears in the + right pane of the Guest Control File Manager. + </para> + </listitem> + + <listitem> + <para> + Transfer files between the guest and the host system by + using the move and copy file transfer icons. + </para> + + <para> + You can copy and move files from the guest to the host + system or from the host system to the guest. + </para> + </listitem> + + <listitem> + <para> + Close the Guest Control File Manager. + </para> + + <para> + Click <emphasis role="bold">Close</emphasis> to end the + guest session. + </para> + </listitem> + + </orderedlist> + + </sect2> + + </sect1> + + <sect1 id="guestadd-guestcontrol"> + + <title>Guest Control of Applications</title> + + <para> + The Guest Additions enable starting of applications inside a guest + VM from the host system. This feature can be used to automate + deployment of software within the guest. + </para> + + <para> + For this to work, the application needs to be installed on the + guest. No additional software needs to be installed on the host. + Additionally, text mode output to stdout and stderr can be shown + on the host for further processing. There are options to specify + user credentials and a timeout value, in milliseconds, to limit + the time the application is able to run. + </para> + + <para> + The Guest Additions for Windows allow for automatic updating. This + applies for already installed Guest Additions versions. Also, + copying files from host to the guest as well as remotely creating + guest directories is available. + </para> + + <para> + To use these features, use the &product-name; command line. See + <xref linkend="vboxmanage-guestcontrol" />. + </para> + + </sect1> + + <sect1 id="guestadd-memory-usage"> + + <title>Memory Overcommitment</title> + + <para> + In server environments with many VMs, the Guest Additions can be + used to share physical host memory between several VMs. This + reduces the total amount of memory in use by the VMs. If memory + usage is the limiting factor and CPU resources are still + available, this can help with running more VMs on each host. + </para> + + <sect2 id="guestadd-balloon"> + + <title>Memory Ballooning</title> + + <para> + The Guest Additions can change the amount of host memory that a + VM uses, while the machine is running. Because of how this is + implemented, this feature is called <emphasis>memory + ballooning</emphasis>. + </para> + + <note> + <itemizedlist> + + <listitem> + <para> + &product-name; supports memory ballooning only on 64-bit + hosts. It is not supported on macOS hosts. + </para> + </listitem> + + <listitem> + <para> + Memory ballooning does not work well with large pages + enabled. To turn off large pages support for a VM, run + <command>VBoxManage modifyvm + <replaceable>vmname</replaceable> --large-pages + off</command> + </para> + </listitem> + + </itemizedlist> + </note> + + <para> + Normally, to change the amount of memory allocated to a virtual + machine, you have to shut down the virtual machine entirely and + modify its settings. With memory ballooning, memory that was + allocated for a virtual machine can be given to another virtual + machine without having to shut the machine down. + </para> + + <para> + When memory ballooning is requested, the &product-name; Guest + Additions, which run inside the guest, allocate physical memory + from the guest operating system on the kernel level and lock + this memory down in the guest. This ensures that the guest will + not use that memory any longer. No guest applications can + allocate it, and the guest kernel will not use it either. + &product-name; can then reuse this memory and give it to another + virtual machine. + </para> + + <para> + The memory made available through the ballooning mechanism is + only available for reuse by &product-name;. It is + <emphasis>not</emphasis> returned as free memory to the host. + Requesting balloon memory from a running guest will therefore + not increase the amount of free, unallocated memory on the host. + Effectively, memory ballooning is therefore a memory + overcommitment mechanism for multiple virtual machines while + they are running. This can be useful to temporarily start + another machine, or in more complicated environments, for + sophisticated memory management of many virtual machines that + may be running in parallel depending on how memory is used by + the guests. + </para> + + <para> + At this time, memory ballooning is only supported through + <command>VBoxManage</command>. Use the following command to + increase or decrease the size of the memory balloon within a + running virtual machine that has Guest Additions installed: + </para> + +<screen>VBoxManage controlvm "VM name" guestmemoryballoon n</screen> + + <para> + where <replaceable>VM name</replaceable> is the name or UUID of + the virtual machine in question and <replaceable>n</replaceable> + is the amount of memory to allocate from the guest in megabytes. + See <xref + linkend="vboxmanage-controlvm" />. + </para> + + <para> + You can also set a default balloon that will automatically be + requested from the VM every time after it has started up with + the following command: + </para> + +<screen>VBoxManage modifyvm "VM name" --guest-memory-balloon n</screen> + + <para> + By default, no balloon memory is allocated. This is a VM + setting, like other <command>modifyvm</command> settings, and + therefore can only be set while the machine is shut down. See + <xref + linkend="vboxmanage-modifyvm" />. + </para> + + </sect2> + + <sect2 id="guestadd-pagefusion"> + + <title>Page Fusion</title> + + <para> + Whereas memory ballooning simply reduces the amount of RAM that + is available to a VM, Page Fusion works differently. It avoids + memory duplication between several similar running VMs. + </para> + + <para> + In a server environment running several similar VMs on the same + host, lots of memory pages are identical. For example, if the + VMs are using identical operating systems. &product-name;'s Page + Fusion technology can efficiently identify these identical + memory pages and share them between multiple VMs. + </para> + + <note> + <para> + &product-name; supports Page Fusion only on 64-bit hosts, and + it is not supported on macOS hosts. Page Fusion currently + works only with Windows 2000 and later guests. + </para> + </note> + + <para> + The more similar the VMs on a given host are, the more + efficiently Page Fusion can reduce the amount of host memory + that is in use. It therefore works best if all VMs on a host run + identical operating systems. Instead of having a complete copy + of each operating system in each VM, Page Fusion identifies the + identical memory pages in use by these operating systems and + eliminates the duplicates, sharing host memory between several + machines. This is called <emphasis>deduplication</emphasis>. If + a VM tries to modify a page that has been shared with other VMs, + a new page is allocated again for that VM with a copy of the + shared page. This is called <emphasis>copy on write</emphasis>. + All this is fully transparent to the virtual machine. + </para> + + <para> + You may be familiar with this kind of memory overcommitment from + other hypervisor products, which call this feature + <emphasis>page sharing</emphasis> or <emphasis>same page + merging</emphasis>. However, Page Fusion differs significantly + from those other solutions, whose approaches have several + drawbacks: + </para> + + <itemizedlist> + + <listitem> + <para> + Traditional hypervisors scan <emphasis>all</emphasis> guest + memory and compute checksums, also called hashes, for every + single memory page. Then, they look for pages with identical + hashes and compare the entire content of those pages. If two + pages produce the same hash, it is very likely that the + pages are identical in content. This process can take rather + long, especially if the system is not idling. As a result, + the additional memory only becomes available after a + significant amount of time, such as hours or sometimes days. + Even worse, this kind of page sharing algorithm generally + consumes significant CPU resources and increases the + virtualization overhead by 10 to 20%. + </para> + + <para> + Page Fusion in &product-name; uses logic in the + &product-name; Guest Additions to quickly identify memory + cells that are most likely identical across VMs. It can + therefore achieve most of the possible savings of page + sharing almost immediately and with almost no overhead. + </para> + </listitem> + + <listitem> + <para> + Page Fusion is also much less likely to be confused by + identical memory that it will eliminate, just to learn + seconds later that the memory will now change and having to + perform a highly expensive and often service-disrupting + reallocation. + </para> + </listitem> + + </itemizedlist> + + <para> + At this time, Page Fusion can only be controlled with + <command>VBoxManage</command>, and only while a VM is shut down. + To enable Page Fusion for a VM, use the following command: + </para> + +<screen>VBoxManage modifyvm "VM name" --page-fusion on</screen> + + <para> + You can observe Page Fusion operation using some metrics. + <literal>RAM/VMM/Shared</literal> shows the total amount of + fused pages, whereas the per-VM metric + <literal>Guest/RAM/Usage/Shared</literal> will return the amount + of fused memory for a given VM. See + <xref linkend="vboxmanage-metrics" /> for information on how to + query metrics. + </para> + + <note> + <para> + Enabling Page Fusion might indirectly increase the chances for + malicious guests to successfully attack other VMs running on + the same host. See <xref linkend="pot-insecure"/>. + </para> + </note> + + </sect2> + + </sect1> + + <sect1 id="guestadd-resizing"> + + <title>Controlling Virtual Monitor Topology</title> + + <sect2 id="guestadd-resizing-linux"> + + <title>X11/Wayland Desktop Environments</title> + + <para> + The Guest Additions provide services for controlling the guest + system's monitor topology. Monitor topology means the resolution + of each virtual monitor and its state (disabled/enabled). The + resolution of a virtual monitor can be modified from the host + side either by resizing the window that hosts the virtual + monitor, by using the <emphasis role="bold">View</emphasis> menu + or the <command>VBoxManage controlvm + <replaceable>vmname</replaceable> setscreenlayout</command> + command. On guest operating systems with X11/Wayland desktops + this is put into effect by either of the following two services: + </para> + +<screen> + VBoxClient --vmsvga + VBoxDRMClient + </screen> + + <para> + The following are some details about guest screen resolution + control functionality: + </para> + + <itemizedlist> + + <listitem> + <para> + On X11/Wayland desktops the resizing service is started + during desktop session initialization, that is desktop + login. On X11 desktops <code>VBoxClient --vmsvga</code> + handles screen topology through the RandR extension. On + Wayland clients <code>VBoxDRMClient</code> is used. The + decision is made automatically at each desktop session + start. + </para> + </listitem> + + <listitem> + <para> + On 32-bit guest operating systems + <command>VBoxDRMClient</command> is always used, in order to + work around bugs. + </para> + </listitem> + + <listitem> + <para> + Since the monitor topology control services are initialized + during the desktop session start, it is impossible to + control the monitor resolution of display managers such as + GDM or LightDM. This default behavior can be changed by + setting the guest property + <literal>/VirtualBox/GuestAdd/DRMResize</literal> of the + virtual machine to any value. See + <xref linkend="guestadd-guestprops" /> for details of how to + update guest properties. When this guest property is set + then <command>VBoxDRMClient</command> is started during the + guest OS boot and stays active all the time, for both the + display manager login screen and the desktop session. + </para> + </listitem> + + </itemizedlist> + + <sect3 id="guestadd-resizing-linux-limitations"> + + <title>Known Limitations</title> + + <para> + <command>VBoxDRMClient</command> is not able to handle + arbitrary guest monitor topologies. Specifically, disabling a + guest monitor that is not the last one invalidates the monitor + topology due to limitations in the + <literal>vmwgfx.ko</literal> Linux kernel module. For example, + when the guest is configured to have four monitors it is not + recommended to disable the second or third monitor. + </para> + + </sect3> + + </sect2> + + </sect1> + +</chapter> diff --git a/doc/manual/en_US/user_Installation.xml b/doc/manual/en_US/user_Installation.xml new file mode 100644 index 00000000..12a83841 --- /dev/null +++ b/doc/manual/en_US/user_Installation.xml @@ -0,0 +1,1535 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="installation"> + + <title>Installation Details</title> + + <para> + As installation of &product-name; varies depending on your host + operating system, the following sections provide installation + instructions for Windows, macOS, Linux, and Oracle Solaris. + </para> + + <sect1 id="installation_windows"> + + <title>Installing on Windows Hosts</title> + + <sect2 id="install-win-prereq"> + + <title>Prerequisites</title> + + <para> + For the various versions of Windows that are supported as host + operating systems, please refer to + <xref linkend="hostossupport" />. + </para> + + <para> + In addition, Windows Installer must be present on your system. + This should be the case for all supported Windows platforms. + </para> + + </sect2> + + <sect2 id="install-win-performing"> + + <title>Performing the Installation</title> + + <para> + The &product-name; installation can be started in either of the + following ways: + </para> + + <itemizedlist> + + <listitem> + <para> + By double-clicking on the executable file. + </para> + </listitem> + + <listitem> + <para> + By entering the following command: + </para> + +<screen>VirtualBox-<version>-<revision>-Win.exe -extract</screen> + + <para> + This will extract the installer into a temporary directory, + along with the .MSI file. Run the following command to + perform the installation: + </para> + +<screen>msiexec /i VirtualBox-<version>-<revision>-Win.msi</screen> + </listitem> + + </itemizedlist> + + <para> + Using either way displays the installation + <emphasis role="bold">Welcome</emphasis> dialog and enables you + to choose where to install &product-name;, and which components + to install. In addition to the &product-name; application, the + following components are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">USB support.</emphasis> This package + contains special drivers for your Windows host that + &product-name; requires to fully support USB devices inside + your virtual machines. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Networking.</emphasis> This package + contains extra networking drivers for your Windows host that + &product-name; needs to support Bridged Networking. This + enables your VM's virtual network cards to be accessed from + other machines on your physical network. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Python support.</emphasis> This + package contains Python scripting support for the + &product-name; API, see <xref linkend="VirtualBoxAPI" />. + For this to work, an already working Windows Python + installation on the system is required. + </para> + + <para> + See, for example: + <ulink url="http://www.python.org/download/windows/" />. + </para> + + <note> + <para> + Python version at least 2.6 is required. Python 3 is also + supported. + </para> + </note> + </listitem> + + </itemizedlist> + + <para> + Depending on your Windows configuration, you may see warnings + about unsigned drivers, or similar. Click + <emphasis role="bold">Continue</emphasis> for these warnings, as + otherwise &product-name; might not function correctly after + installation. + </para> + + <para> + The installer will create an &product-name; group in the Windows + <emphasis role="bold">Start</emphasis> menu, which enables you + to launch the application and access its documentation. + </para> + + <para> + With standard settings, &product-name; will be installed for all + users on the local system. If this is not wanted, you must + invoke the installer by first extracting as follows: + </para> + +<screen>VirtualBox.exe -extract</screen> + + <para> + Then, run either of the following commands on the extracted .MSI + file. This will install &product-name; only for the current + user. + </para> + +<screen>VirtualBox.exe -msiparams ALLUSERS=2</screen> + +<screen>msiexec /i VirtualBox-<version>-Win.msi ALLUSERS=2</screen> + + <para> + If you do not want to install all features of &product-name;, + you can set the optional <literal>ADDLOCAL</literal> parameter + to explicitly name the features to be installed. The following + features are available: + </para> + + <variablelist> + + <varlistentry> + <term> + VBoxApplication + </term> + + <listitem> + <para> + Main binaries of &product-name;. + </para> + + <note> + <para> + This feature must not be absent, since it contains the + minimum set of files to have working &product-name; + installation. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term> + VBoxUSB + </term> + + <listitem> + <para> + USB support. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + VBoxNetwork + </term> + + <listitem> + <para> + All networking support. This includes the VBoxNetworkFlt + and VBoxNetworkAdp features. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + VBoxNetworkFlt + </term> + + <listitem> + <para> + Bridged networking support. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + VBoxNetworkAdp + </term> + + <listitem> + <para> + Host-only networking support + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + VBoxPython + </term> + + <listitem> + <para> + Python support + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + For example, to only install USB support along with the main + binaries, run either of the following commands: + </para> + +<screen>VirtualBox.exe -msiparams ADDLOCAL=VBoxApplication,VBoxUSB</screen> + +<screen>msiexec /i VirtualBox-<version>-Win.msi ADDLOCAL=VBoxApplication,VBoxUSB</screen> + + <para> + The user is able to choose between NDIS5 and NDIS6 host network + filter drivers during the installation. This is done using a + command line parameter, <literal>NETWORKTYPE</literal>. The + NDIS6 driver is the default for most supported Windows hosts. + For some legacy Windows versions, the installer will + automatically select the NDIS5 driver and this cannot be + changed. + </para> + + <para> + You can force an install of the legacy NDIS5 host network filter + driver by specifying <literal>NETWORKTYPE=NDIS5</literal>. For + example, to install the NDIS5 driver on Windows 7 use either of + the following commands: + </para> + +<screen>VirtualBox.exe -msiparams NETWORKTYPE=NDIS5</screen> + +<screen>msiexec /i VirtualBox-<version>-Win;.msi NETWORKTYPE=NDIS5</screen> + + </sect2> + + <sect2 id="install-win-uninstall"> + + <title>Uninstallation</title> + + <para> + As &product-name; uses the standard Microsoft Windows installer, + &product-name; can be safely uninstalled at any time. Click the + program entry in the <emphasis role="bold">Add/Remove + Programs</emphasis> list in the Windows Control Panel. + </para> + + </sect2> + + <sect2 id="install-win-unattended"> + + <title>Unattended Installation</title> + + <para> + Unattended installations can be performed using the standard MSI + support. + </para> + + </sect2> + + <sect2 id="install-win-public-props"> + + <title>Public Properties</title> + + <para> + Public properties can be specified with the MSI API, to control + additional behavior and features of the Windows host installer. + Use either of the following commands: + </para> + +<screen>VirtualBox.exe -msiparams NAME=VALUE [...]</screen> + +<screen>msiexec /i VirtualBox-<version>-Win.msi NAME=VALUE [...]</screen> + + <para> + The following public properties are available. + </para> + + <itemizedlist> + + <listitem> + <para> + VBOX_INSTALLDESKTOPSHORTCUT + </para> + + <para> + Specifies whether or not an &product-name; icon on the + desktop should be created. + </para> + + <para> + Set to <literal>1</literal> to enable, <literal>0</literal> + to disable. Default is 1. + </para> + </listitem> + + <listitem> + <para> + VBOX_INSTALLQUICKLAUNCHSHORTCUT + </para> + + <para> + Specifies whether or not an &product-name; icon in the Quick + Launch Bar should be created. + </para> + + <para> + Set to <literal>1</literal> to enable, <literal>0</literal> + to disable. Default is 1. + </para> + </listitem> + + <listitem> + <para> + VBOX_REGISTERFILEEXTENSIONS + </para> + + <para> + Specifies whether or not the file extensions .vbox, + .vbox-extpack, .ovf, .ova, .vdi, .vmdk, .vhd and .vdd should + be associated with &product-name;. Files of these types then + will be opened with &product-name;. + </para> + + <para> + Set to <literal>1</literal> to enable, <literal>0</literal> + to disable. Default is 1. + </para> + </listitem> + + <listitem> + <para> + VBOX_START + </para> + + <para> + Specifies whether to start &product-name; right after + successful installation. + </para> + + <para> + Set to <literal>1</literal> to enable, <literal>0</literal> + to disable. Default is 1. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + </sect1> + + <sect1 id="installation-mac"> + + <title>Installing on macOS Hosts</title> + + <sect2 id="install-mac-performing"> + + <title>Performing the Installation</title> + + <para> + For macOS hosts, &product-name; ships in a + <filename>dmg</filename> disk image file. Perform the following + steps to install on a macOS host: + </para> + + <orderedlist> + + <listitem> + <para> + Double-click on the <filename>dmg</filename> file, to mount + the contents. + </para> + </listitem> + + <listitem> + <para> + A window opens, prompting you to double-click on the + <filename>VirtualBox.pkg</filename> installer file displayed + in that window. + </para> + </listitem> + + <listitem> + <para> + This starts the installer, which enables you to select where + to install &product-name;. + </para> + </listitem> + + <listitem> + <para> + An &product-name; icon is added to the + <filename>Applications</filename> folder in the Finder. + </para> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="install-mac-uninstall"> + + <title>Uninstallation</title> + + <para> + To uninstall &product-name;, open the disk image + <filename>dmg</filename> file and double-click on the uninstall + icon shown. + </para> + + </sect2> + + <sect2 id="install-mac-unattended"> + + <title>Unattended Installation</title> + + <para> + To perform a non-interactive installation of &product-name; you + can use the command line version of the installer application. + </para> + + <para> + Mount the <filename>dmg</filename> disk image file, as described + in the installation procedure, or use the following command + line: + </para> + +<screen>hdiutil attach /path/to/VirtualBox-xyz.dmg</screen> + + <para> + Open a terminal session and run the following command: + </para> + +<screen>sudo installer -pkg /Volumes/VirtualBox/VirtualBox.pkg -target /Volumes/Macintosh\ HD</screen> + + </sect2> + + </sect1> + + <sect1 id="install-linux-host"> + + <title>Installing on Linux Hosts</title> + + <sect2 id="install-linux-prereq"> + + <title>Prerequisites</title> + + <para> + For the various versions of Linux that are supported as host + operating systems, see <xref linkend="hostossupport" />. + </para> + + <para> + You may need to install the following packages on your Linux + system before starting the installation. Some systems will do + this for you automatically when you install &product-name;. + </para> + + <itemizedlist> + + <listitem> + <para> + Qt 5.3.2 or later. Qt 5.6.2 or later is recommended. + </para> + </listitem> + + <listitem> + <para> + SDL 1.2.7 or later. This graphics library is typically + called <filename>libsdl</filename> or similar. + </para> + </listitem> + + </itemizedlist> + + <note> + <para> + These packages are only required if you want to run the + &product-name; graphical user interfaces. In particular, + <command>VirtualBox</command>, the graphical VirtualBox + Manager, requires both Qt and SDL. If you only want to run + <command>VBoxHeadless</command>, neither Qt nor SDL are + required. + </para> + </note> + + </sect2> + + <sect2 id="externalkernelmodules"> + + <title>The &product-name; Kernel Modules</title> + + <para> + In order to run other operating systems in virtual machines + alongside your main operating system, &product-name; needs to + integrate very tightly with your system. To do this it installs + a driver module called <command>vboxdrv</command> into the + system kernel. The kernel is the part of the operating system + which controls your processor and physical hardware. Without + this kernel module, you can still use &vbox-mgr; to configure + virtual machines, but they will not start. + </para> + + <para> + Network drivers called <command>vboxnetflt</command> and + <command>vboxnetadp</command> are also installed. They enable + virtual machines to make more use of your computer's network + capabilities and are needed for any virtual machine networking + beyond the basic NAT mode. + </para> + + <para> + Since distributing driver modules separately from the kernel is + not something which Linux supports well, the &product-name; + install process creates the modules on the system where they + will be used. This means that you may need to install some + software packages from the distribution which are needed for the + build process. Required packages may include the following: + </para> + + <itemizedlist> + + <listitem> + <para> + GNU compiler (GCC) + </para> + </listitem> + + <listitem> + <para> + GNU Make (make) + </para> + </listitem> + + <listitem> + <para> + Kernel header files + </para> + </listitem> + + </itemizedlist> + + <para> + Also ensure that all system updates have been installed and that + your system is running the most up-to-date kernel for the + distribution. + </para> + + <note> + <para> + The running kernel and the kernel header files must be updated + to matching versions. + </para> + </note> + + <para> + The following list includes some details of the required files + for some common distributions. Start by finding the version name + of your kernel, using the command <command>uname -r</command> in + a terminal. The list assumes that you have not changed too much + from the original installation, in particular that you have not + installed a different kernel type. + </para> + + <itemizedlist> + + <listitem> + <para> + With Debian and Ubuntu-based distributions, you must install + the correct version of the + <filename>linux-headers</filename>, usually whichever of + <filename>linux-headers-generic</filename>, + <filename>linux-headers-amd64</filename>, + <filename>linux-headers-i686</filename> or + <filename>linux-headers-i686-pae</filename> best matches the + kernel version name. Also, the + <filename>linux-kbuild</filename> package if it exists. + Basic Ubuntu releases should have the correct packages + installed by default. + </para> + </listitem> + + <listitem> + <para> + On Fedora, Red Hat, Oracle Linux and many other RPM-based + systems, the kernel version sometimes has a code of letters + or a word close to the end of the version name. For example + "uek" for the Oracle Unbreakable Enterprise Kernel or + "default" or "desktop" for the standard kernels. In this + case, the package name is + <filename>kernel-uek-devel</filename> or equivalent. If + there is no such code, it is usually + <filename>kernel-devel</filename>. + </para> + </listitem> + + <listitem> + <para> + On some SUSE and openSUSE Linux versions, you may need to + install the <filename>kernel-source</filename> and + <filename>kernel-syms</filename> packages. + </para> + </listitem> + + </itemizedlist> + + <para> + If you suspect that something has gone wrong with module + installation, check that your system is set up as described + above and try running the following command, as root: + </para> + +<screen>rcvboxdrv setup</screen> + + <sect3 id="kernel-modules-efi-secure-boot"> + + <title>Kernel Modules and UEFI Secure Boot</title> + + <para> + If you are running on a system using UEFI (Unified Extensible + Firmware Interface) Secure Boot, you may need to sign the + following kernel modules before you can load them: + </para> + + <itemizedlist> + + <listitem> + <para> + <command>vboxdrv</command> + </para> + </listitem> + + <listitem> + <para> + <command>vboxnetadp</command> + </para> + </listitem> + + <listitem> + <para> + <command>vboxnetflt</command> + </para> + </listitem> + + <listitem> + <para> + <command>vboxpci</command> + </para> + </listitem> + + </itemizedlist> + + <para> + See your system documentation for details of the kernel module + signing process. + </para> + + </sect3> + + </sect2> + + <sect2 id="install-linux-performing"> + + <title>Performing the Installation</title> + + <para> + &product-name; is available in a number of package formats + native to various common Linux distributions. See + <xref linkend="hostossupport"/>. In addition, there is an + alternative generic installer (.run) which you can use on + supported Linux distributions. + </para> + + <sect3 id="install-linux-debian-ubuntu"> + + <title>Installing &product-name; from a Debian or Ubuntu Package</title> + + <para> + Download the appropriate package for your distribution. The + following example assumes that you are installing to a 64-bit + Ubuntu Xenial system. Use <command>dpkg</command> to install + the Debian package,as follows: + </para> + +<screen>sudo dpkg -i virtualbox-<replaceable>version-number</replaceable>_Ubuntu_xenial_amd64.deb</screen> + + <para> + The installer will also try to build kernel modules suitable + for the current running kernel. If the build process is not + successful you will be shown a warning and the package will be + left unconfigured. Look at + <filename>/var/log/vbox-install.log</filename> to find out why + the compilation failed. You may have to install the + appropriate Linux kernel headers, see + <xref linkend="externalkernelmodules" />. After correcting any + problems, run the following command: + </para> + +<screen>sudo rcvboxdrv setup</screen> + + <para> + This will start a second attempt to build the module. + </para> + + <para> + If a suitable kernel module was found in the package or the + module was successfully built, the installation script will + attempt to load that module. If this fails, please see + <xref linkend="ts_linux-kernelmodule-fails-to-load" /> for + further information. + </para> + + <para> + Once &product-name; has been successfully installed and + configured, you can start it by clicking + <emphasis role="bold">VirtualBox</emphasis> in your + <emphasis role="bold">Start</emphasis> menu or from the + command line. See <xref linkend="startingvboxonlinux" />. + </para> + + </sect3> + + <sect3 id="install-linux-alt-installer"> + + <title>Using the Alternative Generic Installer (VirtualBox.run)</title> + + <para> + The alternative generic installer performs the following + steps: + </para> + + <itemizedlist> + + <listitem> + <para> + Unpacks the application files to the target directory + <filename>/opt/VirtualBox/</filename>, which cannot be + changed. + </para> + </listitem> + + <listitem> + <para> + Builds and installs the &product-name; kernel modules: + <command>vboxdrv</command>, <command>vboxnetflt</command>, + and <command>vboxnetadp</command>. + </para> + </listitem> + + <listitem> + <para> + Creates <filename>/sbin/rcvboxdrv</filename>, an init + script to start the &product-name; kernel module. + </para> + </listitem> + + <listitem> + <para> + Creates a new system group called + <literal>vboxusers</literal>. + </para> + </listitem> + + <listitem> + <para> + Creates symbolic links in <filename>/usr/bin</filename> to + a shell script <filename>/opt/VirtualBox/VBox</filename> + which does some sanity checks and dispatches to the actual + executables: <command>VirtualBox</command>, + <command>VBoxVRDP</command>, + <command>VBoxHeadless</command> and + <command>VBoxManage</command>. + </para> + </listitem> + + <listitem> + <para> + Creates + <filename>/etc/udev/rules.d/60-vboxdrv.rules</filename>, a + description file for udev, if that is present, which makes + the USB devices accessible to all users in the + <literal>vboxusers</literal> group. + </para> + </listitem> + + <listitem> + <para> + Writes the installation directory to + <filename>/etc/vbox/vbox.cfg</filename>. + </para> + </listitem> + + </itemizedlist> + + <para> + The installer must be executed as root with either + <literal>install</literal> or <literal>uninstall</literal> as + the first parameter. For example: + </para> + +<screen>sudo ./VirtualBox.run install</screen> + + <para> + Or if you do not have the <command>sudo</command> command + available, run the following as root instead: + </para> + +<screen>./VirtualBox.run install</screen> + + <para> + Add every user who needs to access USB devices from a + VirtualBox guests to the group <literal>vboxusers</literal>. + Either use the OS user management tools or run the following + command as root: + </para> + +<screen>sudo usermod -a -G vboxusers username</screen> + + <note> + <para> + The <command>usermod</command> command of some older Linux + distributions does not support the <option>-a</option> + option, which adds the user to the given group without + affecting membership of other groups. In this case, find out + the current group memberships with the + <command>groups</command> command and add all these groups + in a comma-separated list to the command line after the + <option>-G</option> option. For example: <command>usermod -G + <replaceable>group1</replaceable>,<replaceable>group2</replaceable>,vboxusers + <replaceable>username</replaceable></command>. + </para> + </note> + + </sect3> + + <sect3 id="install-linux-manual"> + + <title>Performing a Manual Installation</title> + + <para> + If you cannot use the shell script installer described in + <xref linkend="install-linux-alt-installer"/>, you can perform + a manual installation. Run the installer as follows: + </para> + +<screen>./VirtualBox.run --keep --noexec</screen> + + <para> + This will unpack all the files needed for installation in the + directory <literal>install</literal> under the current + directory. The &product-name; application files are contained + in <filename>VirtualBox.tar.bz2</filename> which you can + unpack to any directory on your system. For example: + </para> + +<screen>sudo mkdir /opt/VirtualBox +sudo tar jxf ./install/VirtualBox.tar.bz2 -C /opt/VirtualBox</screen> + + <para> + To run the same example as root, use the following commands: + </para> + +<screen>mkdir /opt/VirtualBox +tar jxf ./install/VirtualBox.tar.bz2 -C /opt/VirtualBox</screen> + + <para> + The sources for &product-name;'s kernel module are provided in + the <filename>src</filename> directory. To build the module, + change to the directory and use the following command: + </para> + +<screen>make</screen> + + <para> + If everything builds correctly, run the following command to + install the module to the appropriate module directory: + </para> + +<screen>sudo make install</screen> + + <para> + In case you do not have sudo, switch the user account to root + and run the following command: + </para> + +<screen>make install</screen> + + <para> + The &product-name; kernel module needs a device node to + operate. The above <command>make</command> command will tell + you how to create the device node, depending on your Linux + system. The procedure is slightly different for a classical + Linux setup with a <filename>/dev</filename> directory, a + system with the now deprecated <command>devfs</command> and a + modern Linux system with <command>udev</command>. + </para> + + <para> + On certain Linux distributions, you might experience + difficulties building the module. You will have to analyze the + error messages from the build system to diagnose the cause of + the problems. In general, make sure that the correct Linux + kernel sources are used for the build process. + </para> + + <para> + Note that the <filename>/dev/vboxdrv</filename> kernel module + device node must be owned by root:root and must be + read/writable only for the user. + </para> + + <para> + Next, you install the system initialization script for the + kernel module and activate the initialization script using the + right method for your distribution, as follows: + </para> + +<screen>cp /opt/VirtualBox/vboxdrv.sh /sbin/rcvboxdrv</screen> + + <para> + This example assumes you installed &product-name; to the + <filename>/opt/VirtualBox</filename> directory. + </para> + + <para> + Create a configuration file for &product-name;, as follows: + </para> + +<screen>mkdir /etc/vbox +echo INSTALL_DIR=/opt/VirtualBox > /etc/vbox/vbox.cfg</screen> + + <para> + Create the following symbolic links: + </para> + +<screen>ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VirtualBox +ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VBoxManage +ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VBoxHeadless</screen> + + </sect3> + + <sect3 id="install-linux-update-uninstall"> + + <title>Updating and Uninstalling &product-name;</title> + + <para> + Before updating or uninstalling &product-name;, you must + terminate any virtual machines which are currently running and + exit the &product-name; or VBoxSVC applications. To update + &product-name;, simply run the installer of the updated + version. To uninstall &product-name;, run the installer as + follows: + </para> + +<screen>sudo ./VirtualBox.run uninstall</screen> + + <para> + As root, you can use the following command: + </para> + +<screen>./VirtualBox.run uninstall</screen> + + <para> + You can uninstall the .run package as follows: + </para> + +<screen>/opt/VirtualBox/uninstall.sh</screen> + + <para> + To manually uninstall &product-name;, perform the manual + installation steps in reverse order. + </para> + + </sect3> + + <sect3 id="install-linux-debian-automatic"> + + <title>Automatic Installation of Debian Packages</title> + + <para> + The Debian packages will request some user feedback when + installed for the first time. The debconf system is used to + perform this task. To prevent any user interaction during + installation, default values can be defined. A file + <literal>vboxconf</literal> can contain the following debconf + settings: + </para> + +<screen>virtualbox virtualbox/module-compilation-allowed boolean true +virtualbox virtualbox/delete-old-modules boolean true</screen> + + <para> + The first line enables compilation of the vboxdrv kernel + module if no module was found for the current kernel. The + second line enables the package to delete any old vboxdrv + kernel modules compiled by previous installations. + </para> + + <para> + These default settings can be applied prior to the + installation of the &product-name; Debian package, as follows: + </para> + +<screen>debconf-set-selections vboxconf</screen> + + <para> + In addition there are some common configuration options that + can be set prior to the installation. See + <xref + linkend="linux_install_opts" />. + </para> + + </sect3> + + <sect3 id="install-linux-rpm-automatic"> + + <title>Automatic Installation of RPM Packages</title> + + <para> + The RPM format does not provide a configuration system + comparable to the debconf system. See + <xref linkend="linux_install_opts" /> for how to set some + common installation options provided by &product-name;. + </para> + + </sect3> + + <sect3 id="linux_install_opts"> + + <title>Automatic Installation Options</title> + + <para> + To configure the installation process for .deb and .rpm + packages, you can create a response file named + <filename>/etc/default/virtualbox</filename>. The automatic + generation of the udev rule can be prevented with the + following setting: + </para> + +<screen>INSTALL_NO_UDEV=1</screen> + + <para> + The creation of the group vboxusers can be prevented as + follows: + </para> + +<screen>INSTALL_NO_GROUP=1</screen> + + <para> + If the following line is specified, the package installer will + not try to build the <command>vboxdrv</command> kernel module + if no module fitting the current kernel was found. + </para> + +<screen>INSTALL_NO_VBOXDRV=1</screen> + + </sect3> + + </sect2> + + <sect2 id="install-linux-vboxusers"> + + <title>The vboxusers Group</title> + + <para> + The Linux installers create the system user group + <literal>vboxusers</literal> during installation. Any system + user who is going to use USB devices from &product-name; guests + must be a member of that group. A user can be made a member of + the group <literal>vboxusers</literal> either by using the + desktop user and group tools, or with the following command: + </para> + +<screen>sudo usermod -a -G vboxusers username</screen> + + </sect2> + + <sect2 id="startingvboxonlinux"> + + <title>Starting &product-name; on Linux</title> + + <para> + The easiest way to start an &product-name; program is by running + the program of your choice (<command>VirtualBox</command>, + <command>VBoxManage</command>, or + <command>VBoxHeadless</command>) from a terminal. These are + symbolic links to <command>VBox.sh</command> that start the + required program for you. + </para> + + <para> + The following detailed instructions should only be of interest + if you wish to execute &product-name; without installing it + first. You should start by compiling the + <command>vboxdrv</command> kernel module and inserting it into + the Linux kernel. &product-name; consists of a service daemon, + <command>VBoxSVC</command>, and several application programs. + The daemon is automatically started if necessary. All + &product-name; applications will communicate with the daemon + through UNIX local domain sockets. There can be multiple daemon + instances under different user accounts and applications can + only communicate with the daemon running under the user account + as the application. The local domain socket resides in a + subdirectory of your system's directory for temporary files + called <filename>.vbox-<username>-ipc</filename>. In case + of communication problems or server startup problems, you may + try to remove this directory. + </para> + + <para> + All &product-name; applications (<command>VirtualBox</command>, + <command>VBoxManage</command>, and + <command>VBoxHeadless</command>) require the &product-name; + directory to be in the library path, as follows: + </para> + +<screen>LD_LIBRARY_PATH=. ./VBoxManage showvminfo "Windows XP"</screen> + + </sect2> + + </sect1> + + <sect1 id="install-solaris-host"> + + <title>Installing on Oracle Solaris Hosts</title> + + <para> + For the specific versions of Oracle Solaris that are supported as + host operating systems, see <xref linkend="hostossupport" />. + </para> + + <para> + If you have a previously installed instance of &product-name; on + your Oracle Solaris host, please uninstall it first before + installing a new instance. See + <xref linkend="uninstall-solaris-host" /> for uninstall + instructions. + </para> + + <sect2 id="install-solaris-performing"> + + <title>Performing the Installation</title> + + <para> + &product-name; is available as a standard Oracle Solaris + package. Download the &product-name; SunOS package, which + includes the 64-bit version of &product-name;. <emphasis>The + installation must be performed as root and from the global + zone</emphasis>. This is because the &product-name; installer + loads kernel drivers, which cannot be done from non-global + zones. To verify which zone you are currently in, execute the + <command>zonename</command> command. + </para> + + <para> + To start installation, run the following commands: + </para> + +<screen>gunzip -cd VirtualBox-<replaceable>version-number</replaceable>-SunOS.tar.gz | tar xvf -</screen> + + <para> + The &product-name; kernel package is integrated into the main + package. Install the &product-name; package as follows: + </para> + +<screen>pkgadd -d VirtualBox-<replaceable>version-number</replaceable>-SunOS.pkg</screen> + + <para> + The installer will then prompt you to enter the package you wish + to install. Choose <emphasis role="bold">1</emphasis> or + <emphasis role="bold">all</emphasis> and proceed. Next the + installer will ask you if you want to allow the postinstall + script to be executed. Choose <emphasis role="bold">y</emphasis> + and proceed, as it is essential to execute this script which + installs the &product-name; kernel module. Following this + confirmation the installer will install &product-name; and + execute the postinstall setup script. + </para> + + <para> + Once the postinstall script has been executed your installation + is now complete. You may now safely delete the uncompressed + package and <filename>autoresponse</filename> files from your + system. &product-name; is installed in + <filename>/opt/VirtualBox</filename>. + </para> + + <note> + <para> + If you need to use &product-name; from non-global zones, see + <xref linkend="solaris-zones" />. + </para> + </note> + + </sect2> + + <sect2 id="install-solaris-vboxuser"> + + <title>The vboxuser Group</title> + + <para> + The installer creates the system user group + <literal>vboxuser</literal> during installation for Oracle + Solaris hosts that support the USB features required by + &product-name;. Any system user who is going to use USB devices + from &product-name; guests must be a member of this group. A + user can be made a member of this group either by using the + desktop user and group tools or by running the following command + as root: + </para> + +<screen>usermod -G vboxuser username</screen> + + <para> + Note that adding an active user to the + <literal>vboxuser</literal> group will require the user to log + out and then log in again. This should be done manually after + successful installation of the package. + </para> + + </sect2> + + <sect2 id="install-solaris-starting"> + + <title>Starting &product-name; on Oracle Solaris</title> + + <para> + The easiest way to start an &product-name; program is by running + the program of your choice (<command>VirtualBox</command>, + <command>VBoxManage</command>, or + <command>VBoxHeadless</command>) from a terminal. These are + symbolic links to <command>VBox.sh</command> that start the + required program for you. + </para> + + <para> + Alternatively, you can directly invoke the required programs + from <filename>/opt/VirtualBox</filename>. Using the links + provided is easier as you do not have to enter the full path. + </para> + + <para> + You can configure some elements of the + <command>VirtualBox</command> Qt GUI, such as fonts and colours, + by running <command>VBoxQtconfig</command> from the terminal. + </para> + + </sect2> + + <sect2 id="uninstall-solaris-host"> + + <title>Uninstallation</title> + + <para> + Uninstallation of &product-name; on Oracle Solaris requires root + permissions. To perform the uninstallation, start a root + terminal session and run the following command: + </para> + +<screen>pkgrm SUNWvbox</screen> + + <para> + After confirmation, this will remove &product-name; from your + system. + </para> + + </sect2> + + <sect2 id="install-solaris-unattended"> + + <title>Unattended Installation</title> + + <para> + To perform a non-interactive installation of &product-name; + there is a response file named + <filename>autoresponse</filename>. The installer uses this for + responses to inputs, rather than prompting the user. + </para> + + <para> + Extract the tar.gz package as described in + <xref linkend="install-solaris-performing"/>. Then open a root + terminal session and run the following command: + </para> + +<screen>pkgadd -d VirtualBox-<replaceable>version-number</replaceable>-SunOS-x86 -n -a autoresponse SUNWvbox</screen> + + <para> + To perform a non-interactive uninstallation, open a root + terminal session and run the following command: + </para> + +<screen>pkgrm -n -a /opt/VirtualBox/autoresponse SUNWvbox</screen> + + </sect2> + + <sect2 id="solaris-zones"> + + <title>Configuring a Zone for Running &product-name;</title> + + <para> + Assuming that &product-name; has already been installed into + your zone, you need to give the zone access to &product-name;'s + device node. This is done by performing the following steps. + Start a root terminal and run the following command: + </para> + +<screen>zonecfg -z <replaceable>vboxzone</replaceable></screen> + + <para> + Replace <replaceable>vboxzone</replaceable> with the name of the + zone where you intend to run &product-name;. + </para> + + <para> + Use <command>zonecfg</command> to add the + <literal>device</literal> resource and <literal>match</literal> + properties to the zone, as follows: + </para> + +<screen>zonecfg:vboxzone>add device +zonecfg:vboxzone:device>set match=/dev/vboxdrv +zonecfg:vboxzone:device>end +zonecfg:vboxzone>add device +zonecfg:vboxzone:device>set match=/dev/vboxdrvu +zonecfg:vboxzone:device>end +zonecfg:vboxzone>exit</screen> + + <para> + On Oracle Solaris 11 or later, you may also add a device for + <filename>/dev/vboxusbmon</filename>, similar to that shown + above. + </para> + + <para> + If you are not using sparse root zones, you will need to + loopback mount <filename>/opt/VirtualBox</filename> from the + global zone into the non-global zone at the same path. This is + specified below using the <literal>dir</literal> attribute and + the <literal>special</literal> attribute. For example: + </para> + +<screen>zonecfg:vboxzone>add fs +zonecfg:vboxzone:device>set dir=/opt/VirtualBox +zonecfg:vboxzone:device>set special=/opt/VirtualBox +zonecfg:vboxzone:device>set type=lofs +zonecfg:vboxzone:device>end +zonecfg:vboxzone>exit</screen> + + <para> + Reboot the zone using <command>zoneadm</command> and you should + be able to run &product-name; from within the configured zone. + </para> + + </sect2> + + </sect1> + + <sect1 id="install-ext-pack"> + + <title>Installing an Extension Pack</title> + + <para> + Extension packs provide extra functionality to the &product-name; + base package, such as extended USB device support and cloud + integration features. See <xref linkend="intro-installing"/>. + </para> + + <para> + To install an &product-name; extension pack, do the following: + </para> + + <orderedlist> + + <listitem> + <para> + Double-click on the extension package file name. + </para> + + <para> + &product-name; extension packs have a + <filename>.vbox-extpack</filename> file name extension. + </para> + </listitem> + + <listitem> + <para> + Follow the on-screen instructions to install the extension + pack. + </para> + </listitem> + + </orderedlist> + + <para> + You can also use the Extension Pack Manager tool to install an + extension pack. See <xref linkend="install-ext-pack-manager"/>. + </para> + + <sect2 id="install-ext-pack-manager"> + + <title>The Extension Pack Manager</title> + + <para> + Extension packs can be installed and managed using the + <emphasis role="bold">Extension Pack Manager</emphasis> tool in + &vbox-mgr;. + </para> + + <para> + The Extension Pack Manager lists the extension packs that are + currently installed on the host, and enables you to install and + uninstall extension packs. + </para> + + <para> + To display the Extension Pack Manager, go to the global + <emphasis role="bold">Tools</emphasis> menu and click + <emphasis role="bold">Extensions</emphasis>. The Extension Pack + Manager is shown. + </para> + + <para> + To install an extension pack using the Extension Pack Manager, + click <emphasis role="bold">Install</emphasis> and select an + extension package file. The extension pack is installed on the + host and listed in Extension Pack Manager. + </para> + + <para> + To uninstall an extension pack with the Extension Pack Manager, + do the following: + </para> + + <orderedlist> + + <listitem> + <para> + Select the extension pack in the Extension Pack Manager + window and click <emphasis role="bold">Uninstall</emphasis>. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Remove</emphasis> in the prompt + dialog. + </para> + + <para> + The extension pack is uninstalled from the host and removed + from the Extension Pack Manager. + </para> + </listitem> + + </orderedlist> + + <para> + Alternatively, you can use the <command>VBoxManage</command> + command line to install and manage &product-name; extension + packs. See <xref linkend="vboxmanage-extpack" />. + </para> + + </sect2> + + </sect1> + +</chapter> diff --git a/doc/manual/en_US/user_Introduction.xml b/doc/manual/en_US/user_Introduction.xml new file mode 100644 index 00000000..f4cae028 --- /dev/null +++ b/doc/manual/en_US/user_Introduction.xml @@ -0,0 +1,6796 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="Introduction"> + + <title>First Steps</title> + + <para> + Welcome to &product-name;. + </para> + + <para> + &product-name; is a cross-platform virtualization application. What + does that mean? For one thing, it installs on your existing Intel or + AMD-based computers, whether they are running Windows, macOS, Linux, + or Oracle Solaris operating systems (OSes). Secondly, it extends the + capabilities of your existing computer so that it can run multiple + OSes, inside multiple virtual machines, at the same time. As an + example, you can run Windows and Linux on your Mac, run Windows + Server on your Linux server, run Linux on your Windows PC, and so + on, all alongside your existing applications. You can install and + run as many virtual machines as you like. The only practical limits + are disk space and memory. + </para> + + <para> + &product-name; is deceptively simple yet also very powerful. It can + run everywhere from small embedded systems or desktop class machines + all the way up to datacenter deployments and even Cloud + environments. + </para> + + <para> + The following screenshot shows how &product-name;, installed on an + Apple Mac computer, is running Windows Server 2016 in a virtual + machine window. + </para> + + <figure id="fig-win2016-intro"> + <title>Windows Server 2016 Virtual Machine, Displayed on a macOS Host</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/vm-vista-running.png" + width="14cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + In this User Manual, we will begin simply with a quick introduction + to virtualization and how to get your first virtual machine running + with the easy-to-use &product-name; graphical user interface. + Subsequent chapters will go into much more detail covering more + powerful tools and features, but fortunately, it is not necessary to + read the entire User Manual before you can use &product-name;. + </para> + + <para> + You can find a summary of &product-name;'s capabilities in + <xref linkend="features-overview" />. For existing &product-name; + users who just want to find out what is new in this release, see the + <xref linkend="ChangeLog"/>. + </para> + + <sect1 id="virt-why-useful"> + + <title>Why is Virtualization Useful?</title> + + <para> + The techniques and features that &product-name; provides are + useful in the following scenarios: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Running multiple operating systems + simultaneously.</emphasis> &product-name; enables you to run + more than one OS at a time. This way, you can run software + written for one OS on another, such as Windows software on + Linux or a Mac, without having to reboot to use it. Since you + can configure what kinds of <emphasis>virtual</emphasis> + hardware should be presented to each such OS, you can install + an old OS such as DOS or OS/2 even if your real computer's + hardware is no longer supported by that OS. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Easier software + installations.</emphasis> Software vendors can use virtual + machines to ship entire software configurations. For example, + installing a complete mail server solution on a real machine + can be a tedious task. With &product-name;, such a complex + setup, often called an <emphasis>appliance</emphasis>, can be + packed into a virtual machine. Installing and running a mail + server becomes as easy as importing such an appliance into + &product-name;. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Testing and disaster + recovery.</emphasis> Once installed, a virtual machine and its + virtual hard disks can be considered a + <emphasis>container</emphasis> that can be arbitrarily frozen, + woken up, copied, backed up, and transported between hosts. + </para> + + <para> + Using virtual machines enables you to build and test a + multi-node networked service, for example. Issues with + networking, operating system, and software configuration can + be investigated easily. + </para> + + <para> + In addition to that, with the use of another &product-name; + feature called <emphasis>snapshots</emphasis>, one can save a + particular state of a virtual machine and revert back to that + state, if necessary. This way, one can freely experiment with + a computing environment. If something goes wrong, such as + problems after installing software or infecting the guest with + a virus, you can easily switch back to a previous snapshot and + avoid the need of frequent backups and restores. + </para> + + <para> + Any number of snapshots can be created, allowing you to travel + back and forward in virtual machine time. You can delete + snapshots while a VM is running to reclaim disk space. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Infrastructure consolidation.</emphasis> + Virtualization can significantly reduce hardware and + electricity costs. Most of the time, computers today only use + a fraction of their potential power and run with low average + system loads. A lot of hardware resources as well as + electricity is thereby wasted. So, instead of running many + such physical computers that are only partially used, one can + pack many virtual machines onto a few powerful hosts and + balance the loads between them. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="virtintro"> + + <title>Some Terminology</title> + + <para> + When dealing with virtualization, and also for understanding the + following chapters of this documentation, it helps to acquaint + oneself with a bit of crucial terminology, especially the + following terms: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Host operating system (host + OS).</emphasis> This is the OS of the physical computer on + which &product-name; was installed. There are versions of + &product-name; for Windows, macOS, Linux, and Oracle Solaris + hosts. See <xref linkend="hostossupport" />. + </para> + + <para> + Most of the time, this manual discusses all &product-name; + versions together. There may be platform-specific differences + which we will point out where appropriate. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Guest operating system (guest + OS).</emphasis> This is the OS that is running inside the + virtual machine. Theoretically, &product-name; can run any x86 + OS such as DOS, Windows, OS/2, FreeBSD, and OpenBSD. But to + achieve near-native performance of the guest code on your + machine, we had to go through a lot of optimizations that are + specific to certain OSes. So while your favorite OS + <emphasis>may</emphasis> run as a guest, we officially support + and optimize for a select few, which include the most common + OSes. + </para> + + <para> + See <xref linkend="guestossupport" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Virtual machine (VM).</emphasis> This is + the special environment that &product-name; creates for your + guest OS while it is running. In other words, you run your + guest OS <emphasis>in</emphasis> a VM. Normally, a VM is shown + as a window on your computer's desktop. Depending on which of + the various frontends of &product-name; you use, the VM might + be shown in full screen mode or remotely on another computer. + </para> + + <para> + Internally, &product-name; treats a VM as a set of parameters + that specify its behavior. Some parameters describe hardware + settings, such as the amount of memory and number of CPUs + assigned. Other parameters describe the state information, + such as whether the VM is running or saved. + </para> + + <para> + You can view these VM settings in &vbox-mgr;, in the + <emphasis role="bold">Settings</emphasis> window, and by + running the <command>VBoxManage</command> command. See + <xref linkend="vboxmanage" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Guest Additions.</emphasis> This refers + to special software packages which are shipped with + &product-name; but designed to be installed + <emphasis>inside</emphasis> a VM to improve performance of the + guest OS and to add extra features. See + <xref linkend="guestadditions" />. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="features-overview"> + + <title>Features Overview</title> + + <para> + The following is a brief outline of &product-name;'s main + features: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Portability.</emphasis> &product-name; + runs on a large number of 64-bit host operating systems. See + <xref linkend="hostossupport" />. + </para> + + <para> + &product-name; is a so-called <emphasis>hosted</emphasis> + hypervisor, sometimes referred to as a <emphasis>type + 2</emphasis> hypervisor. Whereas a + <emphasis>bare-metal</emphasis> or <emphasis>type 1</emphasis> + hypervisor runs directly on the hardware, &product-name; + requires an existing OS to be installed. It can thus run + alongside existing applications on that host. + </para> + + <para> + To a very large degree, &product-name; is functionally + identical on all of the host platforms, and the same file and + image formats are used. This enables you to run virtual + machines created on one host on another host with a different + host OS. For example, you can create a virtual machine on + Windows and then run it on Linux. + </para> + + <para> + In addition, virtual machines can easily be imported and + exported using the Open Virtualization Format (OVF), an + industry standard created for this purpose. You can even + import OVFs that were created with a different virtualization + software. See <xref linkend="ovf" />. + </para> + + <para> + For users of &oci; the functionality extends to exporting and + importing virtual machines to and from the cloud. This + simplifies development of applications and deployment to the + production environment. See + <xref linkend="cloud-export-oci"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Guest Additions: shared folders, + seamless windows, 3D virtualization.</emphasis> The + &product-name; Guest Additions are software packages which can + be installed <emphasis>inside</emphasis> of supported guest + systems to improve their performance and to provide additional + integration and communication with the host system. After + installing the Guest Additions, a virtual machine will support + automatic adjustment of video resolutions, seamless windows, + accelerated 3D graphics and more. See + <xref linkend="guestadditions" />. + </para> + + <para> + In particular, Guest Additions provide for <emphasis>shared + folders</emphasis>, which let you access files on the host + system from within a guest machine. See + <xref linkend="sharedfolders" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Comprehensive hardware + support.</emphasis> Among other features, &product-name; + supports the following: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Guest multiprocessing + (SMP).</emphasis> &product-name; can present up to 32 + virtual CPUs to each virtual machine, irrespective of how + many CPU cores are physically present on your host. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">USB device support.</emphasis> + &product-name; implements a virtual USB controller and + enables you to connect arbitrary USB devices to your + virtual machines without having to install device-specific + drivers on the host. USB support is not limited to certain + device categories. See <xref linkend="settings-usb" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Hardware compatibility.</emphasis> + &product-name; virtualizes a vast array of virtual + devices, among them many devices that are typically + provided by other virtualization platforms. That includes + IDE, SCSI, and SATA hard disk controllers, several virtual + network cards and sound cards, virtual serial and parallel + ports and an Input/Output Advanced Programmable Interrupt + Controller (I/O APIC), which is found in many computer + systems. This enables easy cloning of disk images from + real machines and importing of third-party virtual + machines into &product-name;. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Full ACPI support.</emphasis> The + Advanced Configuration and Power Interface (ACPI) is fully + supported by &product-name;. This enables easy cloning of + disk images from real machines or third-party virtual + machines into &product-name;. With its unique + <emphasis>ACPI power status support</emphasis>, + &product-name; can even report to ACPI-aware guest OSes + the power status of the host. For mobile systems running + on battery, the guest can thus enable energy saving and + notify the user of the remaining power, for example in + full screen modes. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Multiscreen resolutions.</emphasis> + &product-name; virtual machines support screen resolutions + many times that of a physical screen, allowing them to be + spread over a large number of screens attached to the host + system. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Built-in iSCSI support.</emphasis> + This unique feature enables you to connect a virtual + machine directly to an iSCSI storage server without going + through the host system. The VM accesses the iSCSI target + directly without the extra overhead that is required for + virtualizing hard disks in container files. See + <xref linkend="storage-iscsi" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">PXE Network boot.</emphasis> The + integrated virtual network cards of &product-name; fully + support remote booting using the Preboot Execution + Environment (PXE). + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Multigeneration branched + snapshots.</emphasis> &product-name; can save arbitrary + snapshots of the state of the virtual machine. You can go back + in time and revert the virtual machine to any such snapshot + and start an alternative VM configuration from there, + effectively creating a whole snapshot tree. See + <xref linkend="snapshots" />. You can create and delete + snapshots while the virtual machine is running. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VM groups.</emphasis> &product-name; + provides a groups feature that enables the user to organize + and control virtual machines collectively, as well as + individually. In addition to basic groups, it is also possible + for any VM to be in more than one group, and for groups to be + nested in a hierarchy. This means you can have groups of + groups. In general, the operations that can be performed on + groups are the same as those that can be applied to individual + VMs: Start, Pause, Reset, Close (Save state, Send Shutdown, + Poweroff), Discard Saved State, Show in File System, Sort. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Clean architecture and unprecedented + modularity.</emphasis> &product-name; has an extremely modular + design with well-defined internal programming interfaces and a + clean separation of client and server code. This makes it easy + to control it from several interfaces at once. For example, + you can start a VM simply by clicking on a button in the + &product-name; graphical user interface and then control that + machine from the command line, or even remotely. See + <xref linkend="frontends" />. + </para> + + <para> + Due to its modular architecture, &product-name; can also + expose its full functionality and configurability through a + comprehensive <emphasis role="bold">software development kit + (SDK),</emphasis> which enables integration of &product-name; + with other software systems. See + <xref linkend="VirtualBoxAPI" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Remote machine display.</emphasis> The + VirtualBox Remote Desktop Extension (VRDE) enables + high-performance remote access to any running virtual machine. + This extension supports the Remote Desktop Protocol (RDP) + originally built into Microsoft Windows, with special + additions for full client USB support. + </para> + + <para> + The VRDE does not rely on the RDP server that is built into + Microsoft Windows. Instead, the VRDE is plugged directly into + the virtualization layer. As a result, it works with guest + OSes other than Windows, even in text mode, and does not + require application support in the virtual machine either. The + VRDE is described in detail in <xref linkend="vrde" />. + </para> + + <para> + On top of this special capacity, &product-name; offers you + more unique features: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Extensible RDP + authentication.</emphasis> &product-name; already supports + Winlogon on Windows and PAM on Linux for RDP + authentication. In addition, it includes an easy-to-use + SDK which enables you to create arbitrary interfaces for + other methods of authentication. See + <xref linkend="vbox-auth" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">USB over RDP.</emphasis> Using RDP + virtual channel support, &product-name; also enables you + to connect arbitrary USB devices locally to a virtual + machine which is running remotely on an &product-name; RDP + server. See <xref linkend="usb-over-rdp" />. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="hostossupport"> + + <title>Supported Host Operating Systems</title> + + <para> + Currently, &product-name; runs on the following host OSes: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Windows hosts (64-bit):</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + Windows 8.1 + </para> + </listitem> + + <listitem> + <para> + Windows 10 + </para> + </listitem> + + <listitem> + <para> + Windows 11 21H2 + </para> + </listitem> + + <listitem> + <para> + Windows Server 2012 + </para> + </listitem> + + <listitem> + <para> + Windows Server 2012 R2 + </para> + </listitem> + + <listitem> + <para> + Windows Server 2016 + </para> + </listitem> + + <listitem> + <para> + Windows Server 2019 + </para> + </listitem> + + <listitem> + <para> + Windows Server 2022 + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">macOS hosts (64-bit):</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + 10.15 (Catalina) + </para> + </listitem> + + <listitem> + <para> + 11 (Big Sur) + </para> + </listitem> + + <listitem> + <para> + 12 (Monterey) + </para> + </listitem> + + </itemizedlist> + + <para> + Intel hardware is required. See also + <xref linkend="KnownIssues" />. + </para> + + <para> + An installer package is available for macOS/Arm64, for systems + using an Apple silicon CPU. With this package, you can run + some guest operating systems for Intel x86/x64 CPUs in an + emulation. + </para> + + <para> + The macOS/Arm64 installer package for Apple silicon platform + is available as a Developer Preview release. This package + represents a work in progress project and the performance is + very modest. + </para> + + <note> + <para> + Developer Preview is a public release for developers, which + provides early access to unsupported software release and + features. + </para> + </note> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Linux hosts (64-bit).</emphasis> + Includes the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Ubuntu 18.04 LTS, 20.04 LTS and 22.04 + </para> + </listitem> + + <listitem> + <para> + Debian GNU/Linux 10 ("Buster") and 11 ("Bullseye") + </para> + </listitem> + + <listitem> + <para> + Oracle Linux 7, 8 and 9 + </para> + </listitem> + + <listitem> + <para> + CentOS/Red Hat Enterprise Linux 7, 8 and 9 + </para> + </listitem> + + <listitem> + <para> + Fedora 35 and 36 + </para> + </listitem> + + <listitem> + <para> + Gentoo Linux + </para> + </listitem> + + <listitem> + <para> + SUSE Linux Enterprise server 12 and 15 + </para> + </listitem> + + <listitem> + <para> + openSUSE Leap 15.3 + </para> + </listitem> + + </itemizedlist> + + <para> + It should be possible to use &product-name; on most systems + based on Linux kernel 2.6, 3.x, 4.x or 5.x using either the + &product-name; installer or by doing a manual installation. + See <xref linkend="install-linux-host" />. However, the + formally tested and supported Linux distributions are those + for which we offer a dedicated package. + </para> + + <para> + Note that Linux 2.4-based host OSes are no longer supported. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Oracle Solaris hosts (64-bit + only).</emphasis> The following versions are supported with + the restrictions listed in <xref linkend="KnownIssues" />: + </para> + + <itemizedlist> + + <listitem> + <para> + Oracle Solaris 11.4 + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + + <para> + Note that any feature which is marked as + <emphasis>experimental</emphasis> is not supported. Feedback and + suggestions about such features are welcome. + </para> + + <sect2 id="hostcpurequirements"> + + <title>Host CPU Requirements</title> + + <para> + SSE2 (Streaming SIMD Extensions 2) support is required for host + CPUs. + </para> + + </sect2> + + </sect1> + + <sect1 id="intro-installing"> + + <title>Installing &product-name; and Extension Packs</title> + + <para> + &product-name; comes in many different packages, and installation + depends on your host OS. If you have installed software before, + installation should be straightforward. On each host platform, + &product-name; uses the installation method that is most common + and easy to use. If you run into trouble or have special + requirements, see <xref linkend="installation" /> for details + about the various installation methods. + </para> + + <para> + &product-name; is split into the following components: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Base package.</emphasis> The base + package consists of all open source components and is licensed + under the GNU General Public License V2. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Extension packs.</emphasis> Additional + extension packs can be downloaded which extend the + functionality of the &product-name; base package. Currently, + Oracle provides a single extension pack, available from: + <ulink url="http://www.virtualbox.org" />. The extension pack + provides the following added functionality: + </para> + + <itemizedlist> + + <listitem> + <para> + VirtualBox Remote Desktop Protocol (VRDP) support. See + <xref linkend="vrde" />. + </para> + </listitem> + + <listitem> + <para> + Host webcam passthrough. See + <xref linkend="webcam-passthrough" />. + </para> + </listitem> + + <listitem> + <para> + Intel PXE boot ROM. + </para> + </listitem> + +<!-- <listitem> + <para> + Experimental support for PCI passthrough on Linux hosts. + See <xref linkend="pcipassthrough" />. + </para> + </listitem>--> + + <listitem> + <para> + Disk image encryption with AES algorithm. See + <xref linkend="diskencryption" />. + </para> + </listitem> + + <listitem> + <para> + Cloud integration features. See + <xref linkend="cloud-integration"/>. + </para> + </listitem> + + </itemizedlist> + + <para> + For details of how to install an extension pack, see + <xref linkend="install-ext-pack"/>. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="intro-starting"> + + <title>Starting &product-name;</title> + + <para> + After installation, you can start &product-name; as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Windows hosts.</emphasis> In the + <emphasis role="bold">Programs</emphasis> menu, click on the + item in the <emphasis role="bold">VirtualBox</emphasis> group. + On some Windows platforms, you can also enter + <command>VirtualBox</command> in the search box of the + <emphasis role="bold">Start</emphasis> menu. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">macOS hosts.</emphasis> In the Finder, + double-click on the + <emphasis role="bold">VirtualBox</emphasis> item in the + Applications folder. You may want to drag this item onto your + Dock. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Linux or Oracle Solaris + hosts</emphasis>. Depending on your desktop environment, an + &product-name; item may have been placed in either the System + or System Tools group of your + <emphasis role="bold">Applications</emphasis> menu. + Alternatively, you can enter <command>VirtualBox</command> in + a terminal window. + </para> + </listitem> + + </itemizedlist> + + <para> + When you start &product-name;, the &vbox-mgr; interface is shown. + See <xref linkend="gui-virtualboxmanager"/>. + </para> + + </sect1> + + <sect1 id="gui-virtualboxmanager"> + + <title>&vbox-mgr;</title> + + <para> + &vbox-mgr; is the user interface for &product-name;. You can use + &vbox-mgr; to create, configure, and manage your virtual machines. + </para> + + <para> + This section describes the main features of the &vbox-mgr; user + interface. Subsequent sections and chapters describe how to use + &vbox-mgr; to perform tasks in &product-name;. + </para> + + <para> + When you start &product-name;, the + <emphasis role="bold">&vbox-mgr;</emphasis> window is displayed. + </para> + + <para> + <xref linkend="fig-vbox-manager-initial"/> shows &vbox-mgr; the + first time you start &product-name;, before you have created any + virtual machines. + </para> + + <figure id="fig-vbox-manager-initial"> + <title>&vbox-mgr;, Showing Welcome Screen After Initial Startup</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/virtualbox-main-empty.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + <xref linkend="fig-vbox-manager-populated"/> shows how &vbox-mgr; + might look after you have created some virtual machines. + </para> + + <figure id="fig-vbox-manager-populated"> + <title>&vbox-mgr; Window, After Creating Virtual Machines</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/virtualbox-main.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The main components of the &vbox-mgr; window are as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">The machine list.</emphasis> The left + pane of the <emphasis role="bold">VirtualBox + Manager</emphasis> window lists all your virtual machines. If + you have not yet created any virtual machines, this list is + empty. See <xref linkend="gui-machine-list"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">The Details pane.</emphasis> The pane on + the right displays the properties of the currently selected + virtual machine. If you do not have any machines yet, the pane + displays a welcome message. + </para> + + <para> + The toolbar buttons on the Details pane can be used to create + and work with virtual machines. See + <xref linkend="gui-details"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Help Viewer.</emphasis> A window that + displays context-sensitive help topics for &vbox-mgr; tasks. + See <xref linkend="help-viewer"/>. + </para> + </listitem> + + </itemizedlist> + + <sect2 id="gui-machine-list"> + + <title>The Machine List</title> + + <para> + The list of virtual machines in the left pane is called the + <emphasis>machine list</emphasis>. + </para> + + <para> + The following methods can be used to control and configure + virtual machines in the machine list: + </para> + + <itemizedlist> + + <listitem> + <para> + Right-click on the virtual machine name, to display menu + options. + </para> + </listitem> + + <listitem> + <para> + Click on the Machine Tools menu, to the right of the virtual + machine name. See <xref linkend="gui-tools-machine"/>. + </para> + </listitem> + + <listitem> + <para> + Click a button in the toolbar in the Details pane. See + <xref linkend="gui-details"/>. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="gui-details"> + + <title>The Details Pane</title> + + <para> + The Details pane shows configuration information for a virtual + machine that is selected in the machine list. The pane also + includes a toolbar for performing tasks. + </para> + + <figure id="fig-vbox-details-pane"> + <title>&vbox-mgr; Details Pane, Including Toolbar</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/details-pane.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The Details pane includes the following: + </para> + + <simplesect id="gui-details-toolbar"> + + <title>&vbox-mgr; Toolbar</title> + + <para> + A toolbar at the top of the Details pane contains buttons that + enable you to configure the selected virtual machine, or to + create a new virtual machine. + </para> + + <para> + The toolbar includes the following buttons: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">New.</emphasis> Creates a new + virtual machine, and adds it to the machine list. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Add.</emphasis> Adds an existing + virtual machine to the machine list. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Settings.</emphasis> Displays the + <emphasis role="bold">Settings</emphasis> window for the + virtual machine, enabling you to make configuration + changes. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Discard.</emphasis> For a running + virtual machine, discards the saved state for the virtual + machine and closes it down. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Show/Start.</emphasis> For a running + virtual machine, <emphasis role="bold">Show</emphasis> + displays the virtual machine window. For a stopped virtual + machine, <emphasis role="bold">Start</emphasis> displays + options for powering up the virtual machine. + </para> + </listitem> + + </itemizedlist> + + </simplesect> + + <simplesect id="gui-details-settings"> + + <title>Settings</title> + + <para> + A summary of settings is shown for the virtual machine. + </para> + + <para> + You can change some virtual machine settings, by clicking on + the setting in the Details pane. + </para> + + <note> + <para> + If a virtual machine is running, some settings cannot be + altered. You must stop the virtual machine first in order to + change the setting. + </para> + </note> + + <para> + Virtual machine settings can also be changed using the + <emphasis role="bold">Settings</emphasis> button on the + &vbox-mgr; toolbar. + </para> + + <para> + The virtual machine settings on the Details pane are organized + in sections that correspond to those used in the + <emphasis role="bold">Settings</emphasis> window. See + <xref linkend="BasicConcepts"/>. + </para> + + <para> + Click the arrow icon to hide or show each section. + </para> + + </simplesect> + + <simplesect id="gui-details-preview"> + + <title>Preview Window</title> + + <para> + The virtual machine display is shown in a small window. + </para> + + <para> + You can use the Preview window to check if your virtual + machine has finished booting up. + </para> + + <para> + Click the arrow icon to hide or show the Preview window. + </para> + + </simplesect> + + <simplesect id="gui-notification-center"> + + <title>Notification Center</title> + + <para> + Notification messages may be shown in a sliding panel on the + right of the Details pane, called the + <emphasis role="bold">Notification Center</emphasis>. Click + the warning triangle to show the notification messages. + </para> + + <para> + Most system messages that do not require user interaction are + displayed in the Notification Center, including task failure + alerts. + </para> + + <para> + The progress of some tasks can be observed and stopped using + the Notification Center. + </para> + + </simplesect> + + </sect2> + + <sect2 id="gui-tools"> + + <title>&vbox-mgr; Tools</title> + + <para> + &vbox-mgr; provides two types of user tools, to enable you to + perform common tasks easily. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Global Tools.</emphasis> These tools + apply to <emphasis>all</emphasis> virtual machines. See + <xref linkend="gui-tools-global"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Machine Tools.</emphasis> These tools + apply to a <emphasis>specific</emphasis> virtual machine. + See <xref linkend="gui-tools-machine"/>. + </para> + </listitem> + + </itemizedlist> + + <simplesect id="gui-tools-global"> + + <title>Global Tools</title> + + <para> + In the left pane of the &vbox-mgr; window, click the + <emphasis role="bold">Menu</emphasis> icon in the + <emphasis role="bold">Tools</emphasis> banner located above + the machine list. The <emphasis role="bold">Global + Tools</emphasis> menu is displayed. + </para> + + <figure id="fig-global-tools-menu"> + <title>Global Tools Menu</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/global-tools-menu.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + A drop-down list enables you to select from the following + global tools: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Welcome.</emphasis> Displays the + &vbox-mgr; welcome message. The &vbox-mgr; toolbar is also + included, to enable you to get started with using + &product-name;. See + <xref linkend="fig-vbox-manager-initial"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Extensions.</emphasis> Displays the + <emphasis role="bold">Extension Pack Manager</emphasis> + tool. This tool is used to install and uninstall + &product-name; Extension Packs. See + <xref linkend="install-ext-pack-manager"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Media.</emphasis> Displays the + <emphasis role="bold">Virtual Media Manager</emphasis> + tool. This tool is used to manage the disk images used by + &product-name;. See + <xref linkend="virtual-media-manager"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Network.</emphasis> Displays the + <emphasis role="bold">Network Manager</emphasis> tool. + This tool is used to create and configure some types of + networks used by &product-name;. See + <xref linkend="network-manager"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Cloud.</emphasis> Displays the + <emphasis role="bold">Cloud Profile Editor</emphasis> + tool. This tool is used to configure connections to a + cloud service, such as &oci;. See + <xref linkend="cloud-using-cloud-profile-manager"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Activities.</emphasis> Displays the + <emphasis role="bold">VM Activity Overview</emphasis> + tool. This tool is used to monitor performance and + resource usage of virtual machines. See + <xref linkend="vm-info"/>. + </para> + </listitem> + + </itemizedlist> + + <para> + The <emphasis role="bold">Pin</emphasis> icon is used to keep + the <emphasis role="bold">Tools</emphasis> banner visible as + you scroll down the entries in the machine list. + </para> + + </simplesect> + + <simplesect id="gui-tools-machine"> + + <title>Machine Tools</title> + + <para> + In the machine list in the left pane of the &vbox-mgr; window, + select a virtual machine. + </para> + + <para> + Click the <emphasis role="bold">Menu</emphasis> icon to the + right of the virtual machine name. The + <emphasis role="bold">Machine Tools</emphasis> menu is + displayed. + </para> + + <figure id="fig-machine-tools-menu"> + <title>Machine Tools Menu</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/machine-tools-menu.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + A drop-down list enables you to select from the following + machine tools: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Details.</emphasis> Displays the + Details pane for the selected virtual machine. See + <xref linkend="gui-details"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Snapshots.</emphasis> Displays the + <emphasis role="bold">Snapshots</emphasis> tool. This tool + enables you to view and manage snapshots for the virtual + machine. See <xref linkend="snapshots"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Logs.</emphasis> Displays the + <emphasis role="bold">Log Viewer</emphasis> tool. This + tool enables you to view and search system logs for the + virtual machine. See <xref linkend="log-viewer"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Activity.</emphasis> Displays the + <emphasis role="bold">VM Activity</emphasis> page of the + <emphasis role="bold">Session Information</emphasis> + dialog. This dialog enables you to view and analyze + performance metrics for the virtual machine. See + <xref linkend="vm-info"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">File Manager.</emphasis> Displays + the <emphasis role="bold">Guest Control File + Manager</emphasis> tool. This tool enables you to manage + files on the guest system. See + <xref linkend="guestadd-gc-file-manager"/>. + </para> + </listitem> + + </itemizedlist> + + </simplesect> + + </sect2> + + <sect2 id="help-viewer"> + + <title>Help Viewer</title> + + <para> + The Help Viewer is a window that displays context-sensitive help + to assist you in completing common &vbox-mgr; tasks. You can + display the Help Viewer in the following ways: + </para> + + <itemizedlist> + + <listitem> + <para> + In a &vbox-mgr; wizard or dialog, click + <emphasis role="bold">Help</emphasis> to display the + relevant help topic. + </para> + </listitem> + + <listitem> + <para> + In &vbox-mgr; or from a guest VM, do either of the + following: + </para> + + <itemizedlist> + + <listitem> + <para> + Select the <emphasis role="bold">Help</emphasis>, + <emphasis role="bold">Contents</emphasis> menu option. + </para> + </listitem> + + <listitem> + <para> + Press the <emphasis role="bold">F1</emphasis> button. + </para> + + <para> + The keyboard shortcut used to access the Help Viewer can + be configured in the + <emphasis role="bold">Preferences</emphasis> window. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + + <para> + The Help Viewer has the following features: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Navigation tools.</emphasis> The left + hand pane contains the following navigation tools: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Contents.</emphasis> Displays the + help topic location in the &product-name; documentation. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Search.</emphasis> Enables you to + search the documentation for help topics. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Bookmarks.</emphasis> Enables you + to bookmark useful help topics. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Tabbed browsing.</emphasis> Help + topics that you have visited are displayed in tabs in the + main window pane. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Zoomable topics.</emphasis> Zoom + controls enable you to enlarge help topic details. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Printing.</emphasis> Help topics can + be printed to PDF file or to a local printer. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="vboxmanager-wizards"> + + <title>About &vbox-mgr; Wizards</title> + + <para> + &vbox-mgr; includes wizards that enable you to complete tasks + easily. Examples of such tasks are when you create a new virtual + machine or use the cloud integration features of &product-name;. + </para> + + <para> + To display a help topic for the wizard, click the + <emphasis role="bold">Help</emphasis> button. + </para> + + <para> + Some wizards can be displayed in either of the following modes: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Guided mode.</emphasis> This is the + default display mode. Wizards are shown in the conventional + manner, using a series of pages with descriptions to guide + the user through the steps for a task. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold"><emphasis role="bold">Expert + mode.</emphasis></emphasis> This display mode is designed + for more advanced users of &product-name;. All settings are + displayed on a single page, enabling quicker completion of + tasks. + </para> + </listitem> + + </itemizedlist> + + <para> + Click the button at the bottom of the wizard window to switch + between Guided mode and Expert mode. + </para> + + </sect2> + + </sect1> + + <sect1 id="create-vm-wizard"> + + <title>Creating Your First Virtual Machine</title> + + <para> + Click <emphasis role="bold">New</emphasis> in the VirtualBox + Manager window. The <emphasis role="bold">Create Virtual + Machine</emphasis> wizard is shown, to guide you through the + required steps for setting up a new virtual machine (VM). + </para> + + <para> + The <emphasis role="bold">Create Virtual Machine</emphasis> wizard + pages are described in the following sections. + </para> + + <sect2 id="create-vm-wizard-name-os"> + + <title>Create Virtual Machine Wizard: Name and Operating System</title> + + <figure id="fig-create-vm-name"> + <title>Creating a Virtual Machine: Name and Operating System</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/create-vm-1.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + Use this page to specify a name and operating system (OS) for + the virtual machine and to change the storage location used for + VMs. + </para> + + <para> + You can also choose to disable the unattended guest operating + system install feature. See also + <xref linkend="create-vm-wizard-unattended-install"/>. + </para> + + <para> + The following fields are available on this wizard page: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Name.</emphasis> A name for the new + VM. The name you enter is shown in the machine list of + &vbox-mgr; and is also used for the virtual machine's files + on disk. + </para> + + <para> + Be sure to assign each VM an informative name that describes + the OS and software running on the VM. For example, a name + such as <literal>Windows 10 with Visio</literal>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Folder.</emphasis> The location where + VMs are stored on your computer, called the + <emphasis>machine folder</emphasis>. The default folder + location is shown. + </para> + + <para> + Ensure that the folder location has enough free space, + especially if you intend to use the snapshots feature. See + also <xref linkend="vboxconfigdata-machine-folder"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">ISO Image.</emphasis> Select an ISO + image file. The image file can be used to install an OS on + the new virtual machine or it can be attached to a DVD drive + on the new virtual machine. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Type and Version.</emphasis> These + fields are used to select the OS that you want to install on + the new virtual machine. + </para> + + <para> + The supported OSes are grouped into types. If you want to + install something very unusual that is not listed, select + the <emphasis role="bold">Other</emphasis> type. Depending + on your selection, &product-name; will enable or disable + certain VM settings that your guest OS may require. This is + particularly important for 64-bit guests. See + <xref linkend="intro-64bitguests" />. It is therefore + recommended to always set this field to the correct value. + </para> + + <para> + If an ISO image is selected and &product-name; detects the + operating system for the ISO, the + <emphasis role="bold">Type</emphasis> and + <emphasis role="bold">Version</emphasis> fields are + populated automatically and are disabled. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Skip Unattended + Installation.</emphasis> Disables unattended guest OS + installation, even if an ISO image is selected that supports + unattended installation. In that case, the selected ISO + image is mounted automatically on the DVD drive of the new + virtual machine and user interaction is required to complete + the OS installation. + </para> + + <para> + The unattended installation step in the wizard is skipped. + </para> + + <note> + <para> + This option is disabled if you do not select an + installation medium in the <emphasis role="bold">ISO + Image</emphasis> field. + </para> + </note> + </listitem> + + </itemizedlist> + + <para> + Click <emphasis role="bold">Next</emphasis> to go to the next + wizard page. + </para> + + </sect2> + + <sect2 id="create-vm-wizard-unattended-install"> + + <title>(Optional) Create Virtual Machine Wizard: Unattended Guest OS Install</title> + + <para> + Unattended guest OS installation enables you to install the OS + on a virtual machine automatically. + </para> + + <note> + <para> + This page is optional. It is not displayed if you have + selected the <emphasis role="bold">Skip Unattended + Installation</emphasis> option on the initial wizard page. + </para> + </note> + + <para> + Use this page to set up the required parameters for unattended + guest OS installation and to configure automatic installation of + the &product-name; Guest Additions. See also + <xref linkend="create-vm-wizard-unattended-examples"/> for some + typical scenarios when using automated installation. + </para> + + <figure id="fig-create-vm-unattended-install"> + <title>Creating a Virtual Machine: Unattended Guest OS Installation</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/create-vm-2.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The following fields are available on this wizard page: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Username and Password.</emphasis> + Enter the credentials for a default user on the guest OS. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Guest Additions.</emphasis> Enables + automatic installation of the Guest Additions, following + installation of the guest OS. Use the drop-down list to + select the location of the ISO image file for the Guest + Additions. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Additional Options.</emphasis> The + following options enable you to perform extra configuration + of the guest OS: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Product Key.</emphasis> For + Windows guests only. Enter the product key required for + Windows installation. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Hostname.</emphasis> Host name for + the guest. By default, this is the same as the VM name. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Domain Name.</emphasis> Domain + name for the guest. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Install in Background.</emphasis> + Enable headless mode for the VM, where a graphical user + interface is not shown. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + + <para> + Click <emphasis role="bold">Next</emphasis> to go to the next + wizard page. + </para> + + </sect2> + + <sect2 id="create-vm-wizard-hardware"> + + <title>Create Virtual Machine Wizard: Hardware</title> + + <para> + Use this page to configure hardware settings for the virtual + machine. + </para> + + <figure id="fig-create-vm-hardware"> + <title>Creating a Virtual Machine: Hardware</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/create-vm-3.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The following fields are available on this wizard page: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Base Memory.</emphasis> Select the + amount of RAM that &product-name; should allocate every time + the virtual machine is started. The amount of memory + selected here will be taken away from your host machine and + presented to the guest OS, which will report this size as + the virtual machines installed RAM. + </para> + + <caution> + <para> + Choose this setting carefully. The memory you give to the + VM will not be available to your host OS while the VM is + running, so do not specify more than you can spare. + </para> + + <para> + For example, if your host machine has 4 GB of RAM and you + enter 2048 MB as the amount of RAM for a particular + virtual machine, you will only have 2 GB left for all the + other software on your host while the VM is running. If + you run two VMs at the same time, even more memory will be + allocated for the second VM, which may not even be able to + start if that memory is not available. + </para> + + <para> + On the other hand, you should specify as much as your + guest OS and your applications will require to run + properly. A guest OS may require at least 1 or 2 GB of + memory to install and boot up. For best performance, more + memory than that may be required. + </para> + </caution> + + <para> + Always ensure that the host OS has enough RAM remaining. If + insufficient RAM remains, the system might excessively swap + memory to the hard disk, which effectively brings the host + system to a standstill. + </para> + + <para> + As with other <emphasis role="bold">Create Virtual + Machine</emphasis> wizard settings, you can change this + setting later, after you have created the VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Processor(s).</emphasis> Select the + number of virtual processors to assign to the VM. + </para> + + <para> + It is not advised to assign more than half of the total + processor threads from the host machine. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable EFI.</emphasis> Enables + Extensible Firware Interface (EFI) booting for the guest OS. + </para> + </listitem> + + </itemizedlist> + + <para> + Click <emphasis role="bold">Next</emphasis> to go to the next + wizard page. + </para> + + </sect2> + + <sect2 id="create-vm-wizard-virtual-hard-disk"> + + <title>Create Virtual Machine Wizard: Virtual Hard Disk</title> + + <para> + Use this page to specify a virtual hard disk for the virtual + machine. + </para> + + <para> + There are many ways in which &product-name; can provide hard + disk space to a VM, see <xref linkend="storage" />. The most + common way is to use a large image file on your physical hard + disk, whose contents &product-name; presents to your VM as if it + were a complete hard disk. This file then represents an entire + hard disk, so you can even copy it to another host and use it + with another &product-name; installation. + </para> + + <figure id="fig-create-vm-hard-disk"> + <title>Creating a New Virtual Machine: Virtual Hard Disk</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/create-vm-4.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The following fields are available on this wizard page: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Create a Virtual Hard Disk + Now</emphasis>. Creates a new empty virtual hard disk image, + located in the VM's machine folder. + </para> + + <para> + Enter the following settings: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Disk Size</emphasis>. Use the + slider to select a maximum size for the hard disk in the + new VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Pre-Allocate Full Size.</emphasis> + This setting determines the type of image file used for + the disk image. Select this setting to use a + <emphasis>fixed-size file</emphasis> for the disk image. + Deselect this setting to use a <emphasis>dynamically + allocated file</emphasis> for the disk image. + </para> + + <para> + The different types of image file behave as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Dynamically allocated + file.</emphasis> This type of image file only grows + in size when the guest actually stores data on its + virtual hard disk. Therefore, this file is small + initially. As the drive is filled with data, the + file grows to the specified size. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Fixed-size file.</emphasis> + This type of image file immediately occupies the + file specified, even if only a fraction of that + virtual hard disk space is actually in use. While + occupying much more space, a fixed-size file incurs + less overhead and is therefore slightly faster than + a dynamically allocated file. + </para> + </listitem> + + </itemizedlist> + + <para> + For more details about the differences, see + <xref linkend="vdidetails" />. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Use an Existing Hard Disk + File.</emphasis> Enables you to select an + <emphasis>existing</emphasis> disk image file to use with + the new VM. + </para> + + <para> + The drop-down list presented in the window lists all disk + images which are known by &product-name;. These disk images + are currently attached to a virtual machine, or have been + attached to a virtual machine. + </para> + + <para> + Alternatively, click on the small folder icon next to the + drop-down list. In the <emphasis role="bold">Hard Disk + Selector</emphasis> window that is displayed, click + <emphasis role="bold">Add</emphasis> to select a disk image + file on your host disk. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Do Not Add a Virtual Hard + Disk.</emphasis> The new VM is created without a hard disk. + </para> + </listitem> + + </itemizedlist> + + <para> + To prevent your physical hard disk on the host OS from filling + up, &product-name; limits the size of the image file. But the + image file must be large enough to hold the contents of the + guest OS and the applications you want to install. For a Windows + or Linux guest, you will probably need several gigabytes for any + serious use. The limit of the image file size can be changed + later, see <xref linkend="vboxmanage-modifymedium"/>. + </para> + + <note> + <para> + You can skip attaching a virtual hard disk file to the new + virtual machine you are creating. But you will then need to + attach an hard disk later on, in order to install a guest + operating system. + </para> + </note> + + <para> + After having selected or created your image file, click + <emphasis role="bold">Next</emphasis> to go to the next wizard + page. + </para> + + </sect2> + + <sect2 id="create-vm-wizard-summary"> + + <title>Create Virtual Machine Wizard: Summary</title> + + <para> + This page displays a summary of the configuration for the + virtual machine. + </para> + + <para> + If you are not happy with any of the settings, use the + <emphasis role="bold">Back</emphasis> button to return to the + corresponding page and modify the setting. + </para> + + <para> + Click <emphasis role="bold">Finish</emphasis> to create your new + virtual machine. The virtual machine is displayed in the machine + list on the left side of the &vbox-mgr; window, with the name + that you entered on the first page of the wizard. + </para> + + </sect2> + + <sect2 id="create-vm-wizard-unattended-examples"> + + <title>Some Examples of Unattended Installation</title> + + <para> + To configure unattended installation, you typically just need to + specify an ISO image in the <emphasis role="bold">Create Virtual + Machine</emphasis> wizard. &product-name; then detects the OS + type and the unattended installation process is done + automatically when the wizard is completed. However, in some + situations the installation may need be completed manually. + </para> + + <para> + The following list describes some common scenarios for + unattended installation: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">OS type is detected + automatically.</emphasis> The following outcomes are + possible: + </para> + + <itemizedlist> + + <listitem> + <para> + If unattended installation is supported for the selected + ISO, the guest OS is installed automatically. No user + input is required. + </para> + </listitem> + + <listitem> + <para> + If unattended installation is not supported for the + selected ISO, the ISO image is inserted automatically + into the DVD drive of the new VM. The guest OS + installation must then be completed manually. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">OS type is not detected + automatically.</emphasis> You must configure + <emphasis role="bold">Type</emphasis> and + <emphasis role="bold">Version</emphasis> settings in the + wizard. + </para> + + <para> + The ISO image is inserted automatically into the DVD drive + of the new VM. The guest OS installation must then be + completed manually. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Unattended Installation is + disabled.</emphasis> Users can disable unattended + installation, by selecting the <emphasis role="bold">Skip + Unattended Installation</emphasis> check box on the initial + wizard page. + </para> + + <para> + The ISO image is inserted automatically into the DVD drive + of the new VM. The guest OS installation must then be + completed manually. + </para> + </listitem> + + </itemizedlist> + + <para> + See also <xref linkend="basic-unattended"/> for details of how + to perform unattended installation from the command line. + </para> + + </sect2> + + </sect1> + + <sect1 id="intro-running"> + + <title>Running Your Virtual Machine</title> + + <para> + To start a virtual machine, you have the following options: + </para> + + <itemizedlist> + + <listitem> + <para> + Double-click on the VM's entry in the machine list in + &vbox-mgr;. + </para> + </listitem> + + <listitem> + <para> + Select the VM's entry in the machine list in &vbox-mgr;, and + click <emphasis role="bold">Start</emphasis> in the toolbar + the top of the window. + </para> + </listitem> + + <listitem> + <para> + Go to the <filename>VirtualBox VMs</filename> folder in your + system user's home directory. Find the subdirectory of the + machine you want to start and double-click on the machine + settings file. This file has a <filename>.vbox</filename> file + extension. + </para> + </listitem> + + </itemizedlist> + + <para> + Starting a virtual machine displays a new window, and the virtual + machine which you selected will boot up. Everything which would + normally be seen on the virtual system's monitor is shown in the + window. See <xref linkend="fig-win2016-intro"/>. + </para> + + <para> + In general, you can use the virtual machine as you would use a + real computer. The following topics describe a few points to note + when running a VM. + </para> + + <sect2 id="intro-starting-vm-first-time"> + + <title>Starting a New VM for the First Time</title> + + <para> + When you start a VM for the first time the OS installation + process is started automatically, using the ISO image file + specified in the <emphasis role="bold">Create Virtual + Machine</emphasis> wizard. + </para> + + <para> + Follow the onscreen instructions to install your OS. + </para> + +<!-- <para> + If you have physical CD or DVD media from which you want to + install your guest OS, such as a Windows installation CD or DVD, + put the media into your host's CD or DVD drive. + </para> + + <para> + If you have downloaded installation media from the Internet in + the form of an ISO image file such as with a Linux distribution, + you could burn this file to an empty CD or DVD and proceed as + described above. With &product-name; however, you can skip this + step and mount the ISO file directly. &product-name; will then + present this file as a CD or DVD-ROM drive to the virtual + machine, much like it does with virtual hard disk images. + </para>--> + + </sect2> + + <sect2 id="keyb_mouse_normal"> + + <title>Capturing and Releasing Keyboard and Mouse</title> + + <para> + &product-name; provides a virtual USB tablet device to new + virtual machines through which mouse events are communicated to + the guest OS. If you are running a modern guest OS that can + handle such devices, mouse support may work out of the box + without the mouse being <emphasis>captured</emphasis> as + described below. See <xref linkend="settings-motherboard" />. + </para> + + <para> + Otherwise, if the virtual machine detects only standard PS/2 + mouse and keyboard devices, since the OS in the virtual machine + does not know that it is not running on a real computer, it + expects to have exclusive control over your keyboard and mouse. + But unless you are running the VM in full screen mode, your VM + needs to share keyboard and mouse with other applications and + possibly other VMs on your host. + </para> + + <para> + After installing a guest OS and before you install the Guest + Additions, described in <xref linkend="guestadditions"/>, either + your VM or the rest of your computer can + <emphasis>own</emphasis> the keyboard and the mouse. Both cannot + own the keyboard and mouse at the same time. You will see a + <emphasis>second</emphasis> mouse pointer which is always + confined to the limits of the VM window. You activate the VM by + clicking inside it. + </para> + + <para> + To return ownership of keyboard and mouse to your host OS, + &product-name; reserves a special key on your keyboard: the + <emphasis>Host key</emphasis>. By default, this is the + <emphasis>right Ctrl key</emphasis> on your keyboard. On a Mac + host, the default Host key is the left Command key. You can + change this default using the Preferences window. See + <xref linkend="preferences" />. The current setting for the Host + key is always displayed at the bottom right of your VM window. + </para> + + <figure id="fig-host-key"> + <title>Host Key Setting on the Virtual Machine Taskbar</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/vm-hostkey.png" + width="7cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + This means the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Your <emphasis role="bold">keyboard</emphasis> is owned by + the VM if the VM window on your host desktop has the + keyboard focus. If you have many windows open in your guest + OS, the window that has the focus in your VM is used. This + means that if you want to enter text within your VM, click + on the title bar of your VM window first. + </para> + + <para> + To release keyboard ownership, press the Host key. As + explained above, this is typically the right Ctrl key. + </para> + + <para> + Note that while the VM owns the keyboard, some key + sequences, such as Alt+Tab, will no longer be seen by the + host, but will go to the guest instead. After you press the + Host key to reenable the host keyboard, all key presses will + go through the host again, so that sequences such as Alt+Tab + will no longer reach the guest. For technical reasons it may + not be possible for the VM to get all keyboard input even + when it does own the keyboard. Examples of this are the + Ctrl+Alt+Del sequence on Windows hosts or single keys + grabbed by other applications on X11 hosts such as the GNOME + desktop Locate Pointer feature. + </para> + </listitem> + + <listitem> + <para> + Your <emphasis role="bold">mouse</emphasis> is owned by the + VM only after you have clicked in the VM window. The host + mouse pointer will disappear, and your mouse will drive the + guest's pointer instead of your normal mouse pointer. + </para> + + <para> + Note that mouse ownership is independent of that of the + keyboard. Even after you have clicked on a titlebar to be + able to enter text into the VM window, your mouse is not + necessarily owned by the VM yet. + </para> + + <para> + To release ownership of your mouse by the VM, press the Host + key. + </para> + </listitem> + + </itemizedlist> + + <para> + As this behavior is inconvenient, &product-name; provides a set + of tools and device drivers for guest systems called the + &product-name; Guest Additions. These tools make VM keyboard and + mouse operations much more seamless. Most importantly, the Guest + Additions suppress the second "guest" mouse pointer and make + your host mouse pointer work directly in the guest. See + <xref linkend="guestadditions" />. + </para> + + </sect2> + + <sect2 id="specialcharacters"> + + <title>Typing Special Characters</title> + + <para> + Some OSes expect certain key combinations to initiate certain + procedures. The key combinations that you type into a VM might + target the host OS, the &product-name; software, or the guest + OS. The recipient of these keypresses depends on a number of + factors, including the key combination itself. + </para> + + <itemizedlist> + + <listitem> + <para> + Host OSes reserve certain key combinations for themselves. + For example, you cannot use the + <emphasis role="bold">Ctrl+Alt+Delete</emphasis> combination + to reboot the guest OS in your VM, because this key + combination is reserved by the host OS. Even though both + Windows and Linux OSes can intercept this key combination, + the host OS is rebooted automatically. + </para> + + <para> + On Linux and Oracle Solaris hosts, which use the X Window + System, the key combination + <emphasis role="bold">Ctrl+Alt+Backspace</emphasis> normally + resets the X server and restarts the entire graphical user + interface. As the X server intercepts this combination, + pressing it will usually restart your + <emphasis>host</emphasis> graphical user interface and kill + all running programs, including &product-name;, in the + process. + </para> + + <para> + On Linux hosts supporting virtual terminals, the key + combination <emphasis role="bold">Ctrl+Alt+Fx</emphasis>, + where Fx is one of the function keys from F1 to F12, + normally enables you to switch between virtual terminals. As + with <emphasis role="bold">Ctrl+Alt+Delete</emphasis>, these + combinations are intercepted by the host OS and therefore + always switch terminals on the <emphasis>host</emphasis>. + </para> + + <para> + If, instead, you want to send these key combinations to the + <emphasis>guest</emphasis> OS in the virtual machine, you + will need to use one of the following methods: + </para> + + <itemizedlist> + + <listitem> + <para> + Use the items in the + <emphasis role="bold">Input</emphasis>, + <emphasis role="bold">Keyboard</emphasis> menu of the + virtual machine window. This menu includes the settings + <emphasis role="bold">Insert Ctrl+Alt+Delete</emphasis> + and <emphasis role="bold">Insert + Ctrl+Alt+Backspace</emphasis>. However, the latter + setting affects only Linux guests or Oracle Solaris + guests. + </para> + + <para> + This menu also includes an option for inserting the Host + key combination. + </para> + </listitem> + + <listitem> + <para> + Use special key combinations with the Host key, which is + normally the right Control key. &product-name; then + translates the following key combinations for the VM: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Host key + Del</emphasis> + sends <emphasis role="bold">Ctrl+Alt+Del</emphasis> + to reboot the guest OS. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Host key + + Backspace</emphasis> sends + <emphasis role="bold">Ctrl+Alt+Backspace</emphasis> + to restart the graphical user interface of a Linux + or Oracle Solaris guest. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Host key + Function + key</emphasis>. For example, use this key + combination to simulate + <emphasis role="bold">Ctrl+Alt+Fx</emphasis> to + switch between virtual terminals in a Linux guest. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + For some other keyboard combinations such as + <emphasis role="bold">Alt+Tab</emphasis> to switch between + open windows, &product-name; enables you to configure + whether these combinations will affect the host or the + guest, if a virtual machine currently has the focus. This is + a global setting for all virtual machines and can be found + under <emphasis role="bold">File</emphasis>, + <emphasis role="bold">Preferences</emphasis>, + <emphasis role="bold">Input</emphasis>. + </para> + </listitem> + + <listitem> + <para> + A soft keyboard can be used to input key combinations in the + guest. See <xref linkend="soft-keyb"/>. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="intro-removable-media-changing"> + + <title>Changing Removable Media</title> + + <para> + While a virtual machine is running, you can change removable + media in the <emphasis role="bold">Devices</emphasis> menu of + the VM's window. Here you can select in detail what + &product-name; presents to your VM as a CD, DVD, or floppy + drive. + </para> + + <para> + The settings are the same as those available for the VM in the + <emphasis role="bold">Settings</emphasis> window of &vbox-mgr;. + But as the <emphasis role="bold">Settings</emphasis> window is + disabled while the VM is in the Running or Saved state, the + <emphasis role="bold">Devices</emphasis> menu saves you from + having to shut down and restart the VM every time you want to + change media. + </para> + + <para> + Using the <emphasis role="bold">Devices</emphasis> menu, you can + attach the host drive to the guest or select a floppy or DVD + image, as described in <xref linkend="settings-storage" />. + </para> + + <para> + The <emphasis role="bold">Devices</emphasis> menu also includes + an option for creating a virtual ISO (VISO) from selected files + on the host. + </para> + + </sect2> + + <sect2 id="intro-resize-window"> + + <title>Resizing the Machine's Window</title> + + <para> + You can resize the VM's window while that VM is running. When + you do, the window is scaled as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + If you have <emphasis role="bold">scaled mode</emphasis> + enabled, then the virtual machine's screen will be scaled to + the size of the window. This can be useful if you have many + machines running and want to have a look at one of them + while it is running in the background. Alternatively, it + might be useful to enlarge a window if the VM's output + screen is very small, for example because you are running an + old OS in it. + </para> + + <para> + To enable scaled mode, press <emphasis role="bold">Host key + + C</emphasis>, or select <emphasis role="bold">Scaled + Mode</emphasis> from the + <emphasis role="bold">View</emphasis> menu in the VM window. + To leave scaled mode, press <emphasis role="bold">Host key + + C </emphasis>again. + </para> + + <para> + The aspect ratio of the guest screen is preserved when + resizing the window. To ignore the aspect ratio, press + <emphasis role="bold">Shift</emphasis> during the resize + operation. + </para> + + <para> + See <xref linkend="KnownIssues" /> for additional remarks. + </para> + </listitem> + + <listitem> + <para> + If you have the Guest Additions installed and they support + automatic <emphasis role="bold">resizing</emphasis>, the + Guest Additions will automatically adjust the screen + resolution of the guest OS. For example, if you are running + a Windows guest with a resolution of 1024x768 pixels and you + then resize the VM window to make it 100 pixels wider, the + Guest Additions will change the Windows display resolution + to 1124x768. + </para> + + <para> + See <xref linkend="guestadditions" />. + </para> + </listitem> + + <listitem> + <para> + Otherwise, if the window is bigger than the VM's screen, the + screen will be centered. If it is smaller, then scroll bars + will be added to the machine window. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="intro-save-machine-state"> + + <title>Saving the State of the Machine</title> + + <para> + When you click on the <emphasis role="bold">Close</emphasis> + button of your virtual machine window, at the top right of the + window, just like you would close any other window on your + system, &product-name; asks you whether you want to save or + power off the VM. As a shortcut, you can also press + <emphasis role="bold">Host key + Q</emphasis>. + </para> + + <figure id="fig-vm-close"> + <title>Closing Down a Virtual Machine</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/vm-close.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The difference between the three options is crucial. They mean + the following: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Save the machine state:</emphasis> + With this option, &product-name; + <emphasis>freezes</emphasis> the virtual machine by + completely saving its state to your local disk. + </para> + + <para> + When you start the VM again later, you will find that the VM + continues exactly where it was left off. All your programs + will still be open, and your computer resumes operation. + Saving the state of a virtual machine is thus in some ways + similar to suspending a laptop computer by closing its lid. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Send the shutdown signal.</emphasis> + This will send an ACPI shutdown signal to the virtual + machine, which has the same effect as if you had pressed the + power button on a real computer. This should trigger a + proper shutdown mechanism from within the VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Power off the machine:</emphasis> With + this option, &product-name; also stops running the virtual + machine, but <emphasis>without</emphasis> saving its state. + </para> + + <warning> + <para> + This is equivalent to pulling the power plug on a real + computer without shutting it down properly. If you start + the machine again after powering it off, your OS will have + to reboot completely and may begin a lengthy check of its + virtual system disks. As a result, this should not + normally be done, since it can potentially cause data loss + or an inconsistent state of the guest system on disk. + </para> + </warning> + + <para> + As an exception, if your virtual machine has any snapshots, + see <xref linkend="snapshots"/>, you can use this option to + quickly <emphasis role="bold">restore the current + snapshot</emphasis> of the virtual machine. In that case, + powering off the machine will discard the current state and + any changes made since the previous snapshot was taken will + be lost. + </para> + </listitem> + + </itemizedlist> + + <para> + The <emphasis role="bold">Discard</emphasis> button in the + &vbox-mgr; window discards a virtual machine's saved state. This + has the same effect as powering it off, and the same warnings + apply. + </para> + + </sect2> + + </sect1> + + <sect1 id="gui-vmgroups"> + + <title>Using VM Groups</title> + + <para> + VM groups are groups of VMs that you can create as and when + required. You can manage and perform functions on them + collectively, as well as individually. + </para> + + <para> + The following figure shows VM groups displayed in VirtualBox + Manager. + </para> + + <figure id="fig-vm-groups"> + <title>Groups of Virtual Machines</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/vm-groups.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The following features are available for groups: + </para> + + <itemizedlist> + + <listitem> + <para> + Create a group using &vbox-mgr;. Do one of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Drag a VM on top of another VM. + </para> + </listitem> + + <listitem> + <para> + Select multiple VMs and select + <emphasis role="bold">Group</emphasis> from the + right-click menu. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Create and manage a group using the command line. Do one of + the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Create a group and assign a VM. For example: + </para> + +<screen>VBoxManage modifyvm "vm01" --groups "/TestGroup"</screen> + + <para> + This command creates a group <literal>TestGroup</literal> + and attaches the VM <literal>vm01</literal> to that group. + </para> + </listitem> + + <listitem> + <para> + Detach a VM from the group, and delete the group if empty. + For example: + </para> + +<screen>VBoxManage modifyvm "vm01" --groups ""</screen> + + <para> + This command detaches all groups from the VM + <literal>vm01</literal> and deletes the empty group. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Create multiple groups. For example: + </para> + +<screen>VBoxManage modifyvm "vm01" --groups "/TestGroup,/TestGroup2"</screen> + + <para> + This command creates the groups <literal>TestGroup</literal> + and <literal>TestGroup2</literal>, if they do not exist, and + attaches the VM <literal>vm01</literal> to both of them. + </para> + </listitem> + + <listitem> + <para> + Create nested groups, having a group hierarchy. For example: + </para> + +<screen>VBoxManage modifyvm "vm01" --groups "/TestGroup/TestGroup2"</screen> + + <para> + This command attaches the VM <literal>vm01</literal> to the + subgroup <literal>TestGroup2</literal> of the + <literal>TestGroup</literal> group. + </para> + </listitem> + + <listitem> + <para> + Use &vbox-mgr; menu options to control and manage all the VMs + in a group. For example: + <emphasis role="bold">Start</emphasis>, + <emphasis role="bold">Pause</emphasis>, + <emphasis role="bold">Reset</emphasis>, + <emphasis role="bold">Close</emphasis> (save state, send + shutdown signal, poweroff), <emphasis role="bold">Discard + Saved State</emphasis>, <emphasis role="bold">Show in + Explorer</emphasis>, <emphasis role="bold">Sort</emphasis>. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="snapshots"> + + <title>Snapshots</title> + + <para> + With snapshots, you can save a particular state of a virtual + machine for later use. At any later time, you can revert to that + state, even though you may have changed the VM considerably since + then. A snapshot of a virtual machine is thus similar to a machine + in Saved state, but there can be many of them, and these saved + states are preserved. + </para> + + <para> + To see the snapshots of a virtual machine, click on the machine + name in &vbox-mgr;. In the machine tools menu for the VM, click + <emphasis role="bold">Snapshots</emphasis>. The Snapshots tool is + displayed. + </para> + + <figure id="fig-snapshots-tool"> + <title>Snapshots Tool, Showing Snapshot Properties</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/snapshots-1.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + If you select multiple VMs in the machine list, all snapshots are + listed for each VM. + </para> + + <para> + Until you take a snapshot of the virtual machine, the list of + snapshots will be empty, except for the + <emphasis role="bold">Current State</emphasis> item. This item + represents the current point in the lifetime of the virtual + machine. + </para> + + <para> + The Snapshots window includes a toolbar, enabling you to perform + the following snapshot operations: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Take.</emphasis> Takes a snapshot of the + selected VM. See + <xref linkend="snapshots-take-restore-delete"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Delete.</emphasis> Removes a snapshot + from the list of snapshots. See + <xref linkend="snapshots-take-restore-delete"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Restore.</emphasis> Restores the VM + state to be the same as the selected snapshot. See + <xref linkend="snapshots-take-restore-delete"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Properties.</emphasis> Displays the + properties for the selected snapshot. The + <emphasis role="bold">Attributes</emphasis> tab is used to + specify a Name and Description for the snapshot. The + <emphasis role="bold">Information</emphasis> tab shows VM + settings for the snapshot. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Clone.</emphasis> Displays the + <emphasis role="bold">Clone Virtual Machine</emphasis> wizard. + This enables you to create a clone of the VM, based on the + selected snapshot. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Settings.</emphasis> Available for the + Current State snapshot only. Displays the + <emphasis role="bold">Settings</emphasis> window for the VM, + enabling you to make configuration changes. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Discard.</emphasis> For a running VM, + discards the saved state for the VM and closes it down. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Start.</emphasis> Start the VM. This + operation is available for the <emphasis role="bold">Current + State</emphasis> item. + </para> + </listitem> + + </itemizedlist> + + <sect2 id="snapshots-take-restore-delete"> + + <title>Taking, Restoring, and Deleting Snapshots</title> + + <para> + There are three operations related to snapshots, as follows: + </para> + + <orderedlist> + + <listitem> + <para> + <emphasis role="bold">Take a snapshot.</emphasis> This makes + a copy of the machine's current state, to which you can go + back at any given time later. + </para> + + <itemizedlist> + + <listitem> + <para> + If your VM is running: + </para> + + <para> + Select <emphasis role="bold">Take Snapshot</emphasis> + from the <emphasis role="bold">Machine</emphasis> menu + in the VM window. + </para> + + <para> + The VM is paused while the snapshot is being created. + After snapshot creation, the VM continues to run as + normal. + </para> + </listitem> + + <listitem> + <para> + If your VM is in either the Saved or the Powered Off + state, as displayed next to the VM name in the machine + list: + </para> + + <para> + Display the Snapshots window and do one of the + following: + </para> + + <itemizedlist> + + <listitem> + <para> + Click <emphasis role="bold">Take</emphasis> in the + Snapshots window toolbar. + </para> + </listitem> + + <listitem> + <para> + Right-click on the <emphasis role="bold">Current + State </emphasis>item in the list and select + <emphasis role="bold">Take</emphasis>. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + + <para> + A dialog is displayed, prompting you for a snapshot name. + This name is purely for reference purposes, to help you + remember the state of the snapshot. For example, a useful + name would be "Fresh installation from scratch, no Guest + Additions", or "Service Pack 3 just installed". You can also + add a longer text description in the + <emphasis role="bold">Snapshot Description</emphasis> field. + </para> + + <para> + Your new snapshot will then appear in the snapshots list. + Underneath your new snapshot, you will see an item called + <emphasis role="bold">Current State</emphasis>, signifying + that the current state of your VM is a variation based on + the snapshot you took earlier. If you later take another + snapshot, you will see that they are displayed in sequence, + and that each subsequent snapshot is derived from an earlier + one. + </para> + + <figure id="fig-snapshots-list"> + <title>Snapshots List For a Virtual Machine</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/snapshots-2.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + &product-name; imposes no limits on the number of snapshots + you can take. The only practical limitation is disk space on + your host. Each snapshot stores the state of the virtual + machine and thus occupies some disk space. See + <xref linkend="snapshots-contents"/> for details on what is + stored in a snapshot. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Restore a snapshot.</emphasis> In the + Snapshots window, select the snapshot you have taken and + click <emphasis role="bold">Restore</emphasis> in the + toolbar. By restoring a snapshot, you go back or forward in + time. The current state of the machine is lost, and the + machine is restored to the exact state it was in when the + snapshot was taken. + </para> + + <note> + <para> + Restoring a snapshot will affect the virtual hard drives + that are connected to your VM, as the entire state of the + virtual hard drive will be reverted as well. This means + also that all files that have been created since the + snapshot and all other file changes <emphasis>will be + lost. </emphasis>In order to prevent such data loss while + still making use of the snapshot feature, it is possible + to add a second hard drive in + <emphasis>write-through</emphasis> mode using the + <command>VBoxManage</command> interface and use it to + store your data. As write-through hard drives are + <emphasis>not</emphasis> included in snapshots, they + remain unaltered when a machine is reverted. See + <xref linkend="hdimagewrites" />. + </para> + </note> + + <para> + To avoid losing the current state when restoring a snapshot, + you can create a new snapshot before the restore operation. + </para> + + <para> + By restoring an earlier snapshot and taking more snapshots + from there, it is even possible to create a kind of + alternate reality and to switch between these different + histories of the virtual machine. This can result in a whole + tree of virtual machine snapshots. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Delete a snapshot.</emphasis> This + does not affect the state of the virtual machine, but only + releases the files on disk that &product-name; used to store + the snapshot data, thus freeing disk space. To delete a + snapshot, select the snapshot name in the Snapshots window + and click <emphasis role="bold">Delete</emphasis> in the + toolbar. Snapshots can be deleted even while a machine is + running. + </para> + + <note> + <para> + Whereas taking and restoring snapshots are fairly quick + operations, deleting a snapshot can take a considerable + amount of time since large amounts of data may need to be + copied between several disk image files. Temporary disk + files may also need large amounts of disk space while the + operation is in progress. + </para> + </note> + + <para> + There are some situations which cannot be handled while a VM + is running, and you will get an appropriate message that you + need to perform this snapshot deletion when the VM is shut + down. + </para> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="snapshots-contents"> + + <title>Snapshot Contents</title> + + <para> + Think of a snapshot as a point in time that you have preserved. + More formally, a snapshot consists of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + The snapshot contains a complete copy of the VM settings, + including the hardware configuration, so that when you + restore a snapshot, the VM settings are restored as well. + For example, if you changed the hard disk configuration or + the VM's system settings, that change is undone when you + restore the snapshot. + </para> + + <para> + The copy of the settings is stored in the machine + configuration, an XML text file, and thus occupies very + little space. + </para> + </listitem> + + <listitem> + <para> + The complete state of all the virtual disks attached to the + machine is preserved. Going back to a snapshot means that + all changes that had been made to the machine's disks, file + by file and bit by bit, will be undone as well. Files that + were since created will disappear, files that were deleted + will be restored, changes to files will be reverted. + </para> + + <para> + Strictly speaking, this is only true for virtual hard disks + in "normal" mode. You can configure disks to behave + differently with snapshots, see + <xref linkend="hdimagewrites" />. In technical terms, it is + not the virtual disk itself that is restored when a snapshot + is restored. Instead, when a snapshot is taken, + &product-name; creates differencing images which contain + only the changes since the snapshot were taken. When the + snapshot is restored, &product-name; throws away that + differencing image, thus going back to the previous state. + This is both faster and uses less disk space. For the + details, which can be complex, see + <xref linkend="diffimages" />. + </para> + + <para> + Creating the differencing image as such does not occupy much + space on the host disk initially, since the differencing + image will initially be empty and grow dynamically later + with each write operation to the disk. The longer you use + the machine after having created the snapshot, however, the + more the differencing image will grow in size. + </para> + </listitem> + + <listitem> + <para> + If you took a snapshot while the machine was running, the + memory state of the machine is also saved in the snapshot. + This is in the same way that memory can be saved when you + close a VM window. When you restore such a snapshot, + execution resumes at exactly the point when the snapshot was + taken. + </para> + + <para> + The memory state file can be as large as the memory size of + the VM and will therefore occupy considerable disk space. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + </sect1> + + <sect1 id="configbasics"> + + <title>Virtual Machine Configuration</title> + + <para> + When you select a virtual machine from the list in the VirtualBox + Manager window, you will see a summary of that machine's settings + on the right. + </para> + + <para> + Clicking on <emphasis role="bold">Settings</emphasis> displays a + window, where you can configure many of the properties of the + selected VM. But be careful when changing VM settings. It is + possible to change all VM settings after installing a guest OS, + but certain changes might prevent a guest OS from functioning + correctly if done after installation. + </para> + + <note> + <para> + The <emphasis role="bold">Settings</emphasis> button is disabled + while a VM is either in the Running or Saved state. This is + because the <emphasis role="bold">Settings</emphasis> window + enables you to change fundamental characteristics of the virtual + machine that is created for your guest OS. For example, the + guest OS may not perform well if half of its memory is taken + away. As a result, if the + <emphasis role="bold">Settings</emphasis> button is disabled, + shut down the current VM first. + </para> + </note> + + <para> + &product-name; provides a wide range of parameters that can be + changed for a virtual machine. The various settings that can be + changed in the <emphasis role="bold">Settings</emphasis> window + are described in detail in <xref linkend="BasicConcepts" />. Even + more parameters are available when using the + <command>VBoxManage</command> command line interface. See + <xref linkend="vboxmanage" />. + </para> + + </sect1> + + <sect1 id="intro-removing"> + + <title>Removing and Moving Virtual Machines</title> + + <para> + You can remove a VM from &product-name; or move the VM and its + associated files, such as disk images, to another location on the + host. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Removing a VM.</emphasis> To remove a + VM, right-click on the VM in the &vbox-mgr; machine list and + select <emphasis role="bold">Remove</emphasis>. + </para> + + <para> + The confirmation dialog enables you to specify whether to only + remove the VM from the list of machines or to remove the files + associated with the VM. + </para> + + <para> + Note that the <emphasis role="bold">Remove</emphasis> menu + item is disabled while a VM is running. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Moving a VM.</emphasis> To move a VM to + a new location on the host, right-click on the VM in the + &vbox-mgr;'s machine list and select + <emphasis role="bold">Move</emphasis>. + </para> + + <para> + The file dialog prompts you to specify a new location for the + VM. + </para> + + <para> + When you move a VM, &product-name; configuration files are + updated automatically to use the new location on the host. + </para> + + <para> + Note that the <emphasis role="bold">Move</emphasis> menu item + is disabled while a VM is running. + </para> + + <para> + You can also use the <command>VBoxManage movevm</command> + command to move a VM. See <xref linkend="vboxmanage-movevm"/>. + </para> + </listitem> + + </itemizedlist> + + <para> + For information about removing or moving a disk image file from + &product-name;, see <xref linkend="virtual-media-manager"/>. + </para> + + </sect1> + + <sect1 id="clone"> + + <title>Cloning Virtual Machines</title> + + <para> + You can create a full copy or a linked copy of an existing VM. + This copy is called a <emphasis>clone</emphasis>. You might use a + cloned VM to experiment with a VM configuration, to test different + guest OS levels, or to back up a VM. + </para> + + <para> + The <emphasis role="bold">Clone Virtual Machine</emphasis> wizard + guides you through the cloning process. + </para> + + <para> + You can start the Clone Virtual Machine wizard in one of the + following ways: + </para> + + <itemizedlist> + + <listitem> + <para> + Click the VM name in the machine list and then select + <emphasis role="bold">Clone</emphasis> from the + <emphasis role="bold">Machine</emphasis> menu. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Clone</emphasis> in the + <emphasis role="bold">Snapshots</emphasis> window for the + selected VM. + </para> + </listitem> + + </itemizedlist> + + <note> + <para> + The <emphasis role="bold">Clone</emphasis> menu item is disabled + while a virtual machine is running. + </para> + </note> + + <para> + The <emphasis role="bold">New Machine Name and Path</emphasis> + page is displayed. + </para> + + <figure id="fig-clone-wizard-name-path"> + <title>Clone Virtual Machine Wizard: New Machine Name and Path</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/clone-vm-1.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The following clone options are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Name:</emphasis> A name for the cloned + machine. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Path:</emphasis> Choose a location for + the cloned virtual machine, otherwise &product-name; uses the + default machines folder. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">MAC Address Policy:</emphasis> Specifies + whether to retain network card MAC addresses when cloning the + VM. + </para> + + <para> + For example, the <emphasis role="bold">Generate New MAC + Addresses For All Network Adapters</emphasis> value assigns a + new MAC address to each network card during cloning. This is + the default setting. This is the best option when both the + source VM and the cloned VM must operate on the same network. + Other values enable you to retain the existing MAC addresses + in the cloned VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Keep Disk Names:</emphasis> Retains the + disk image names when cloning the VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Keep Hardware UUIDs:</emphasis> Retains + the hardware universally unique identifiers (UUIDs) when + cloning the VM. + </para> + </listitem> + + </itemizedlist> + + <para> + Click <emphasis role="bold">Next</emphasis>. The + <emphasis role="bold">Clone Type</emphasis> page is displayed. + </para> + + <figure id="fig-clone-wizard-clone-type"> + <title>Clone Virtual Machine Wizard: Clone Type</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/clone-vm-2.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The <emphasis role="bold">Clone Type</emphasis> option specifies + whether to create a clone that is linked to the source VM or to + create a fully independent clone: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Full Clone:</emphasis> Copies all + dependent disk images to the new VM folder. A full clone can + operate fully without the source VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Linked Clone:</emphasis> Creates new + differencing disk images based on the source VM disk images. + If you select the current state of the source VM as the clone + point, &product-name; creates a new snapshot. + </para> + </listitem> + + </itemizedlist> + + <para> + (Optional) Click <emphasis role="bold">Next</emphasis>. The + <emphasis role="bold">Snapshots</emphasis> page is displayed. + </para> + + <note> + <para> + The Snapshots page is only displayed for machines that have + snapshots and the selected clone type is + <emphasis role="bold">Full Clone</emphasis>. + </para> + </note> + + <figure id="fig-clone-wizard-snapshots"> + <title>Clone Virtual Machine Wizard: Snapshots</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/clone-vm-3.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + You use this page to select which parts of the snapshot tree to + include in the clone. The available options are as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Current Machine State:</emphasis> Clones + the current state of the VM. Snapshots are not included. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Everything:</emphasis> Clones the + current machine state and all its snapshots. + </para> + </listitem> + + </itemizedlist> + + <para> + Click <emphasis role="bold">Finish</emphasis> to start the clone + operation. + </para> + + <para> + The duration of the clone operation depends on the size and number + of attached disk images. In addition, the clone operation saves + all the differencing disk images of a snapshot. + </para> + + <para> + You can also use the <command>VBoxManage clonevm</command> command + to clone a VM. See <xref linkend="vboxmanage-clonevm" />. + </para> + + </sect1> + + <sect1 id="ovf"> + + <title>Importing and Exporting Virtual Machines</title> + + <para> + &product-name; can import and export virtual machines in the + following formats: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Open Virtualization Format + (OVF).</emphasis> This is the industry-standard format. See + <xref linkend="ovf-about"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Cloud service formats.</emphasis> Export + to and import from cloud services such as &oci; is supported. + See <xref linkend="cloud-integration"/>. + </para> + </listitem> + + </itemizedlist> + + <sect2 id="ovf-about"> + + <title>About the OVF Format</title> + + <para> + OVF is a cross-platform standard supported by many + virtualization products which enables the creation of ready-made + virtual machines that can then be imported into a hypervisor + such as &product-name;. &product-name; makes OVF import and + export easy to do, using &vbox-mgr; or the command-line + interface. + </para> + + <para> + Using OVF enables packaging of <emphasis>virtual + appliances</emphasis>. These are disk images, together with + configuration settings that can be distributed easily. This way + one can offer complete ready-to-use software packages, including + OSes with applications, that need no configuration or + installation except for importing into &product-name;. + </para> + + <note> + <para> + The OVF standard is complex, and support in &product-name; is + an ongoing process. In particular, no guarantee is made that + &product-name; supports all appliances created by other + virtualization software. For a list of known limitations, see + <xref linkend="KnownIssues" />. + </para> + </note> + + <para> + Appliances in OVF format can appear in the following variants: + </para> + + <itemizedlist> + + <listitem> + <para> + They can come in several files, as one or several disk + images, typically in the widely-used VMDK format. See + <xref linkend="vdidetails" />. They also include a textual + description file in an XML dialect with an + <filename>.ovf</filename> extension. These files must then + reside in the same directory for &product-name; to be able + to import them. + </para> + </listitem> + + <listitem> + <para> + Alternatively, the above files can be packed together into a + single archive file, typically with an + <filename>.ova</filename> extension. Such archive files use + a variant of the TAR archive format and can therefore be + unpacked outside of &product-name; with any utility that can + unpack standard TAR files. + </para> + </listitem> + + </itemizedlist> + + <note> + <para> + OVF cannot describe snapshots that were taken for a virtual + machine. As a result, when you export a virtual machine that + has snapshots, only the current state of the machine will be + exported. The disk images in the export will have a + <emphasis>flattened</emphasis> state identical to the current + state of the virtual machine. + </para> + </note> + + </sect2> + + <sect2 id="ovf-import-appliance"> + + <title>Importing an Appliance in OVF Format</title> + + <para> + The following steps show how to import an appliance in OVF + format. + </para> + + <orderedlist> + + <listitem> + <para> + Double-click on the OVF or OVA file. + </para> + + <para> + &product-name; creates file type associations automatically + for any OVF and OVA files on your host OS. + </para> + + <para> + The <emphasis role="bold">Appliance Settings</emphasis> page + of the <emphasis role="bold">Import Virtual + Appliance</emphasis> wizard is shown. + </para> + + <figure id="fig-import-appliance"> + <title>Import Virtual Appliance Wizard: Appliance Settings</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/ovf-import.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + </listitem> + + <listitem> + <para> + The <emphasis role="bold">Appliance Settings</emphasis> page + shows the VMs described in the OVF or OVA file and enables + you to change the VM settings. + </para> + + <para> + By default, membership of VM groups is preserved on import + for VMs that were initially exported from &product-name;. + You can change this behavior by using the + <emphasis role="bold">Primary Group</emphasis> setting for + the VM. + </para> + + <para> + The following global settings apply to all of the VMs that + you import: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Base Folder:</emphasis> Specifies + the directory on the host in which to store the imported + VMs. + </para> + + <para> + If an appliance has multiple VMs, you can specify a + different directory for each VM by editing the + <emphasis role="bold">Base Folder</emphasis> setting for + the VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">MAC Address Policy:</emphasis> + Reinitializes the MAC addresses of network cards in your + VMs prior to import, by default. You can override the + default behavior and preserve the MAC addresses on + import. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Import Hard Drives as + VDI:</emphasis> Imports hard drives in the VDI format + rather than in the default VMDK format. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Finish</emphasis> to import the + appliance. + </para> + + <para> + &product-name; copies the disk images and creates local VMs + with the settings described on the + <emphasis role="bold">Appliance Settings</emphasis> page. + The imported VMs are shown in the list of VMs in VirtualBox + Manager. + </para> + + <para> + Because disk images are large, the VMDK images that are + included with virtual appliances are shipped in a compressed + format that cannot be used directly by VMs. So, the images + are first unpacked and copied, which might take several + minutes. + </para> + </listitem> + + </orderedlist> + + <para> + You can use the <command>VBoxManage import</command> command to + import an appliance. See <xref linkend="vboxmanage-import" />. + </para> + + </sect2> + + <sect2 id="ovf-export-appliance"> + + <title>Exporting an Appliance in OVF Format</title> + + <para> + The following steps show how to export an appliance in OVF + format. + </para> + + <orderedlist> + + <listitem> + <para> + Select <emphasis role="bold">File</emphasis>, + <emphasis role="bold"> Export Appliance</emphasis> to + display the <emphasis role="bold">Export Virtual + Appliance</emphasis> wizard. + </para> + + <para> + On the initial <emphasis role="bold">Virtual + Machines</emphasis> page, you can combine several VMs into + an OVF appliance. + </para> + + <para> + Select one or more VMs to export, and click + <emphasis role="bold">Next</emphasis>. + </para> + </listitem> + + <listitem> + <para> + The <emphasis role="bold">Format Settings</emphasis> page + enables you to configure the following settings: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Format:</emphasis> Selects the + <emphasis role="bold">Open Virtualization + Format</emphasis> value for the output files. + </para> + + <para> + The <emphasis role="bold">&oci;</emphasis> value exports + the appliance to &oci;. See + <xref linkend="cloud-export-oci"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">File:</emphasis> Selects the + location in which to store the exported files. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">MAC Address Policy:</emphasis> + Specifies whether to retain or reassign network card MAC + addresses on export. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Write Manifest File:</emphasis> + Enables you to include a manifest file in the exported + archive file. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Include ISO Image + Files:</emphasis> Enables you to include ISO image files + in the exported archive file. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Next</emphasis> to show the + <emphasis role="bold">Appliance Settings</emphasis> page. + </para> + + <para> + You can edit settings for the virtual appliance. For + example, you can change the name of the virtual appliance or + add product information, such as vendor details or license + text. + </para> + + <para> + Double-click the appropriate field to change its value. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Finish</emphasis> to begin the + export process. Note that this operation might take several + minutes. + </para> + </listitem> + + </orderedlist> + + <para> + You can use the <command>VBoxManage export</command> command to + export an appliance. See <xref linkend="vboxmanage-export" />. + </para> + + </sect2> + + </sect1> + + <sect1 id="cloud-integration"> + + <title>Integrating with &oci;</title> + + <para> + This section describes how to use the features of &product-name; + to integrate with &oci;. + </para> + + <para> + Integrating with &oci; involves the following steps: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Prepare for &oci; + Integration.</emphasis> Before using &product-name; with &oci; + there are some initial configuration steps you may need to do. + See <xref linkend="cloud-integration-steps"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Use &product-name; with + &oci;.</emphasis> <xref linkend="cloud-vbox-oci-tasks"/> + describes how you can use &product-name; with &oci;. + </para> + </listitem> + + </itemizedlist> + + <sect2 id="cloud-integration-steps"> + + <title>Preparing for &oci; Integration</title> + + <para> + Perform the following configuration steps before using + &product-name; to integrate with your &oci; account. + </para> + + <orderedlist> + + <listitem> + <para> + <emphasis role="bold">Install the Extension Pack.</emphasis> + Cloud integration features are only available when you + install the &product-name; Extension Pack. See + <xref linkend="intro-installing"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Create a key pair.</emphasis> Generate + an API signing key pair that is used for API requests to + &oci;. See <xref linkend="cloud-create-api-keypair"/>. + </para> + + <para> + Upload the public key of the key pair from your client + device to the cloud service. See + <xref linkend="cloud-upload-public-key"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Create a cloud profile.</emphasis> The + cloud profile contains resource identifiers for your cloud + account, such as your user OCID, and details of your key + pair. See <xref linkend="cloud-create-cloud-profile"/>. + </para> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="cloud-create-api-keypair"> + + <title>Creating an API Signing Key Pair</title> + + <para></para> + + <para> + To use the cloud integration features of &product-name;, you + must generate an API signing key pair that is used for API + requests to &oci;. + </para> + + <para> + Your API requests are signed with your private key, and &oci; + uses the public key to verify the authenticity of the request. + You must upload the public key to the &oci; Console. + </para> + + <note> + <para> + This key pair is not the same SSH key that you use to access + compute instances on &oci;. + </para> + </note> + + <orderedlist> + + <listitem> + <para> + (Optional) Create a <filename>.oci</filename> directory to + store the key pair. + </para> + +<screen>$ mkdir ~/.oci</screen> + + <para> + The key pair is usually installed in the + <filename>.oci</filename> folder in your home directory. For + example, <filename>~/.oci</filename> on a Linux system. + </para> + </listitem> + + <listitem> + <para> + Generate the private key. + </para> + + <para> + Use the <command>openssl</command> command. + </para> + + <itemizedlist> + + <listitem> + <para> + To generate a private key with a passphrase: + </para> + +<screen>$ openssl genrsa -out ~/.oci/oci_api_key.pem -aes128 2048 </screen> + </listitem> + + <listitem> + <para> + To generate a private key without a passphrase: + </para> + +<screen>$ openssl genrsa -out ~/.oci/oci_api_key.pem 2048</screen> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Change permissions for the private key. + </para> + +<screen>$ chmod 600 ~/.oci/oci_api_key.pem</screen> + + <para> + Generate the public key. + </para> + +<screen>$ openssl rsa -pubout -in ~/.oci/oci_api_key.pem -out ~/.oci/oci_api_key_public.pem</screen> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="cloud-upload-public-key"> + + <title>Uploading the Public Key to &oci;</title> + + <para> + Use the following steps to upload your public key to &oci;. + </para> + + <orderedlist> + + <listitem> + <para> + Log in to the &oci; Console. + </para> + </listitem> + + <listitem> + <para> + Display the <emphasis role="bold">User Settings</emphasis> + page. + </para> + + <para> + Click <emphasis role="bold">Profile</emphasis>, + <emphasis role="bold">User Settings</emphasis>. + </para> + </listitem> + + <listitem> + <para> + Display your current API signing keys. + </para> + + <para> + Click <emphasis role="bold">Resources</emphasis>, + <emphasis role="bold">API Keys</emphasis>. + </para> + </listitem> + + <listitem> + <para> + Upload the public key. + </para> + + <para> + Click <emphasis role="bold">Add Public Key</emphasis>. + </para> + + <para> + The <emphasis role="bold">Add Public Key</emphasis> dialog + is displayed. + </para> + + <figure id="fig-upload-key-oci"> + <title>Upload Public Key Dialog in &oci; Console</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/upload-key.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + Select one of the following options: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Choose Public Key File.</emphasis> + This option enables you to browse to the public key file + on your local hard disk. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Paste Public Keys.</emphasis> This + option enables you to paste the contents of the public + key file into the window in the dialog box. + </para> + </listitem> + + </itemizedlist> + + <para> + Click <emphasis role="bold">Add</emphasis> to upload the + public key. + </para> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="cloud-create-cloud-profile"> + + <title>Creating a Cloud Profile</title> + + <para> + &product-name; uses a <emphasis>cloud profile</emphasis> to + connect to &oci;. A cloud profile is a text file that contains + details of your key files and Oracle Cloud Identifier (OCID) + resource identifiers for your cloud account, such as the + following: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Fingerprint of the public + key.</emphasis> To obtain the fingerprint, you can use the + <command>openssl</command> command: + </para> + +<screen>$ openssl rsa -pubout -outform DER -in ~/.oci/oci_api_key.pem | openssl md5 -c</screen> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Location of the private key on the + client device.</emphasis> Specify the full path to the + private key. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">(Optional) Passphrase for the private + key.</emphasis> This is only required if the key is + encrypted. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Region</emphasis>. Shown on the &oci; + Console. Click + <emphasis role="bold">Administration</emphasis>, + <emphasis role="bold">Tenancy Details</emphasis>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Tenancy OCID.</emphasis> Shown on the + &oci; Console. Click + <emphasis role="bold">Administration</emphasis>, + <emphasis role="bold">Tenancy Details</emphasis>. + </para> + + <para> + A link enables you to copy the Tenancy OCID. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Compartment OCID.</emphasis> Shown on + the &oci; Console. Click + <emphasis role="bold">Identity</emphasis>, + <emphasis role="bold">Compartments</emphasis>. + </para> + + <para> + A link enables you to copy the Compartment OCID. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">User OCID.</emphasis> Shown on the + &oci; Console. Click + <emphasis role="bold">Profile</emphasis>, + <emphasis role="bold">User Settings</emphasis>. + </para> + + <para> + A link enables you to copy the User OCID. + </para> + </listitem> + + </itemizedlist> + + <para> + You can create a cloud profile in the following ways: + </para> + + <itemizedlist> + + <listitem> + <para> + Automatically, by using the <emphasis role="bold">Cloud + Profile Manager</emphasis>. See + <xref linkend="cloud-using-cloud-profile-manager"/>. + </para> + + <para> + The Cloud Profile Manager is a &vbox-mgr; tool that enables + you to create, edit, and manage cloud profiles for your + cloud service accounts. + </para> + </listitem> + + <listitem> + <para> + Automatically, by using the <command>VBoxManage + cloudprofile</command> command. See + <xref linkend="vboxmanage-cloudprofile"/>. + </para> + </listitem> + + <listitem> + <para> + Manually, by creating an <filename>oci_config</filename> + file in your &product-name; global configuration directory. + For example, this is + <filename>$HOME/.config/VirtualBox/oci_config</filename> on + a Linux host. + </para> + </listitem> + + <listitem> + <para> + Manually, by creating a <filename>config</filename> file in + your &oci; configuration directory. For example, this is + <filename>$HOME/.oci/config</filename> on a Linux host. + </para> + + <para> + This is the same file that is used by the &oci; command line + interface. + </para> + + <para> + &product-name; automatically uses the + <filename>config</filename> file if no cloud profile file is + present in your global configuration directory. + Alternatively, you can import this file manually into the + Cloud Profile Manager. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="cloud-using-cloud-profile-manager"> + + <title>Using the Cloud Profile Manager</title> + + <para> + This section describes how to use the Cloud Profile Manager to + create a cloud profile. + </para> + + <para> + To open the Cloud Profile Manager click + <emphasis role="bold">File</emphasis>, + <emphasis role="bold">Cloud Profile Manager</emphasis> in + &vbox-mgr;. + </para> + + <figure id="fig-cloud-profile-manager"> + <title>The Cloud Profile Manager</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/cloud-profile-manager.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + You can use the Cloud Profile Manager in the following ways: + </para> + + <itemizedlist> + + <listitem> + <para> + To create a new cloud profile automatically + </para> + </listitem> + + <listitem> + <para> + To create a cloud profile by importing settings from your + &oci; configuration file. + </para> + </listitem> + + </itemizedlist> + + <para> + Perform the following steps to create a new cloud profile + automatically, using the Cloud Profile Manager: + </para> + + <orderedlist> + + <listitem> + <para> + Click the <emphasis role="bold">Add</emphasis> icon and + specify a <emphasis role="bold">Name</emphasis> for the + profile. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Properties</emphasis> and + specify the following property values for the profile: + </para> + + <itemizedlist> + + <listitem> + <para> + Compartment OCID + </para> + </listitem> + + <listitem> + <para> + Fingerprint of the public key + </para> + </listitem> + + <listitem> + <para> + Location of the private key on the client device + </para> + </listitem> + +<!-- <listitem> + <para> + (Optional) Passphrase for the private key, if the key is + encrypted + </para> + </listitem>--> + + <listitem> + <para> + Region OCID + </para> + </listitem> + + <listitem> + <para> + Tenancy OCID + </para> + </listitem> + + <listitem> + <para> + User OCID + </para> + </listitem> + + </itemizedlist> + + <para> + Some of these are settings for your &oci; account, which you + can view from the &oci; Console. + </para> + </listitem> + + <listitem> + <para> + (Optional) If you are using the cloud profile to connect to + cloud virtual machines, select the + <emphasis role="bold">Show VMs</emphasis> check box. + </para> + + <para> + This creates a new subgroup of the + <emphasis role="bold">OCI</emphasis> group in &vbox-mgr;. + See <xref linkend="cloud-vm-oci-group"/>. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Apply</emphasis> to save your + changes. + </para> + + <para> + The cloud profile settings are saved to the + <filename>oci_config</filename> file in your &product-name; + global settings directory. + </para> + </listitem> + + </orderedlist> + + <para> + Perform the following steps to import an existing &oci; + configuration file into the Cloud Profile Manager: + </para> + + <orderedlist> + + <listitem> + <para> + Ensure that a <filename>config</filename> file is present in + your &oci; configuration directory. For example, this is + <filename>$HOME/.oci/config</filename> on a Linux host. + </para> + </listitem> + + <listitem> + <para> + Click the <emphasis role="bold">Import</emphasis> icon to + open a dialog that prompts you to import cloud profiles from + external files. + </para> + + <warning> + <para> + This action overwrites any cloud profiles that are in your + &product-name; global settings directory. + </para> + </warning> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Import</emphasis>. + </para> + + <para> + Your cloud profile settings are saved to the + <filename>oci_config</filename> file in your &product-name; + global settings directory. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Properties</emphasis> to show + the cloud profile settings. + </para> + + <para> + Double-click on the appropriate field to change the value. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Apply</emphasis> to save your + changes. + </para> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="cloud-vbox-oci-tasks"> + + <title>Using &product-name; With &oci;</title> + + <para> + This section describes how you can use &product-name; with &oci; + to do the following tasks: + </para> + + <itemizedlist> + + <listitem> + <para> + Create, add, and manage &oci; cloud instances using + &vbox-mgr;. See <xref linkend="cloud-vm"/>. + </para> + </listitem> + + <listitem> + <para> + Export an &product-name; VM to &oci;. See + <xref linkend="cloud-export-oci"/>. + </para> + </listitem> + + <listitem> + <para> + Import a cloud instance into &product-name;. See + <xref linkend="cloud-import-oci"/>. + </para> + </listitem> + + <listitem> + <para> + Connect from a local VM to an &oci; cloud subnet. See + <xref linkend="cloud-using-cloud-networks"/>. + </para> + </listitem> + + <listitem> + <para> + Use the <command>VBoxManage</command> commands to integrate + with &oci; and perform cloud operations. See + <xref linkend="cloud-using-cli"/>. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="cloud-vm"> + + <title>Using Cloud Virtual Machines</title> + + <para> + A cloud virtual machine (<emphasis>cloud VM</emphasis>) is a + type of VM that represents an instance on a cloud service. Cloud + VMs are shown in the machine list in &vbox-mgr;, in the same way + as local VMs are. + </para> + + <para> + By using cloud VMs you can create, manage, and control your + &oci; instances from &vbox-mgr;. + </para> + + <note> + <para> + Cloud VMs do not install, export, or import instances to the + &product-name; host. All operations are done remotely on the + cloud service. + </para> + </note> + + <figure id="fig-cloud-vm-overview"> + <title>Cloud VMs, Shown in &vbox-mgr;</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/cloudvm-overview.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + Cloud VMs can be used to do the following tasks in &oci;: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Create a new &oci; + instance.</emphasis> See <xref linkend="cloud-vm-new"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold"> Use an existing &oci; + instance.</emphasis> See <xref linkend="cloud-vm-add"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Configure an &oci; + instance.</emphasis> You can change settings for the + instance, such as display name and shape. See + <xref linkend="cloud-vm-settings"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Control an &oci; instance.</emphasis> + Stop, start, and terminate the instance. See + <xref linkend="cloud-vm-control"/> + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Create a console connection to an + &oci; instance</emphasis>. See + <xref linkend="cloud-vm-instance-console"/>. + </para> + </listitem> + + </itemizedlist> + + <sect3 id="cloud-vm-oci-group"> + + <title>About the OCI VM Group</title> + + <para> + All cloud VMs are shown in the machine list in &vbox-mgr;, in + a special VM group called + <emphasis role="bold">OCI</emphasis>. + </para> + + <para> + Cloud VMs are further grouped according to the cloud profile + used to connect to them. The cloud profile identifies the user + and compartment for the cloud VM and includes details of the + key pair used to connect to cloud instances. See + <xref linkend="cloud-create-cloud-profile"/>. + </para> + + <figure id="fig-cloud-vm-oci-group"> + <title>OCI Group, Containing Cloud VMs</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/cloudvm-oci-group.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + All cloud profiles registered with &product-name; are listed + automatically in the OCI group. + </para> + + <para> + To enable or disable listing of cloud VMs in &vbox-mgr; for a + specific cloud profile, do the following: + </para> + + <para> + Display the <emphasis role="bold">Cloud Profile + Manager</emphasis> and select or deselect the + <emphasis role="bold">List VMs</emphasis> check box for each + cloud profile. + </para> + + </sect3> + + <sect3 id="cloud-vm-new"> + + <title>Creating a New Cloud VM</title> + + <para> + When you create a new cloud VM, a <emphasis>new</emphasis> + &oci; instance is created and associated with the cloud VM. + </para> + + <para> + Perform the following steps to create a new cloud VM: + </para> + + <orderedlist> + + <listitem> + <para> + Click on a cloud profile in the + <emphasis role="bold">OCI</emphasis> group. + </para> + + <para> + The cloud VMs for the selected cloud profile are + displayed. + </para> + </listitem> + + <listitem> + <para> + Select <emphasis role="bold">Group</emphasis>, + <emphasis role="bold">New Machine</emphasis>. + </para> + + <para> + The <emphasis role="bold">Create Cloud Virtual + Machine</emphasis> wizard is displayed. + </para> + + <figure id="fig-cloudvm-new"> + <title>Create Cloud Virtual Machine Wizard</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/cloudvm-new.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + </listitem> + + <listitem> + <para> + On the initial page, configure the following settings for + the new cloud VM: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Location:</emphasis> The cloud + service provider that will host the new instance. + Select <emphasis role="bold">&oci;</emphasis>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Profile:</emphasis> The cloud + profile used to connect to the new instance. Select + from the available cloud profiles. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Source:</emphasis> The image + that the new instance is based on. Choose from the + available images and boot volumes. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Next</emphasis> to display the + <emphasis role="bold">Cloud Virtual Machine + Settings</emphasis> page. + </para> + + <para> + You can use this page to change the default settings for + the new &oci; instance, such as the display name, shape, + and networking configuration. + </para> + + <para> + To add an SSH key to the instance, click the + <emphasis role="bold">SSH Authorised Keys</emphasis> field + and paste the public key into the displayed dialog. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Finish</emphasis> to create a + new &oci; instance using the selected image or boot + volume. The new instance is started automatically. + </para> + + <para> + The new cloud VM is shown in the + <emphasis role="bold">OCI</emphasis> group in &vbox-mgr;. + </para> + </listitem> + + </orderedlist> + + </sect3> + + <sect3 id="cloud-vm-add"> + + <title>Adding a Cloud VM</title> + + <para> + When you add a cloud VM, an <emphasis>existing</emphasis> + &oci; instance is associated with the cloud VM. You can only + add one cloud VM for each instance. + </para> + + <para> + Perform the following steps to add a cloud VM: + </para> + + <orderedlist> + + <listitem> + <para> + Click on a cloud profile in the + <emphasis role="bold">OCI</emphasis> group. + </para> + + <para> + The cloud VMs for the selected cloud profile are + displayed. + </para> + </listitem> + + <listitem> + <para> + Select <emphasis role="bold">Group</emphasis>, + <emphasis role="bold">Add Machine</emphasis>. + </para> + + <para> + The <emphasis role="bold">Add Cloud Virtual + Machine</emphasis> wizard is displayed. + </para> + + <figure id="fig-cloudvm-add"> + <title>Add Cloud Virtual Machine Wizard</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/cloudvm-add.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + </listitem> + + <listitem> + <para> + Configure the following settings: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Source:</emphasis> The cloud + service provider that hosts the instance used for the + cloud VM. Select + <emphasis role="bold">&oci;</emphasis>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Profile:</emphasis> The cloud + profile used to connect to the running instance. + Select from the available cloud profiles. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Instances:</emphasis> The + instance to use for the cloud VM. Choose from the + available instances on your cloud service. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Finish</emphasis> to add a + cloud VM based on the selected instance. + </para> + + <para> + A cloud VM with the same name as the instance is added to + the <emphasis role="bold">OCI</emphasis> group in + &vbox-mgr;. + </para> + </listitem> + + <listitem> + <para> + (Optional) To change the display name for the instance, + click <emphasis role="bold">Settings</emphasis> and edit + the <emphasis role="bold">Display Name</emphasis> field. + </para> + + <para> + The cloud VM name in &vbox-mgr; is updated automatically. + </para> + </listitem> + + </orderedlist> + + </sect3> + + <sect3 id="cloud-vm-settings"> + + <title>Changing Settings for a Cloud VM</title> + + <para> + Select the cloud VM in &vbox-mgr; and click + <emphasis role="bold">Settings</emphasis>. + </para> + + <itemizedlist> + + <listitem> + <para> + For a <emphasis>new</emphasis> cloud VM, you can change + many settings for the &oci; instance, such as the display + name, shape, and disk size. + </para> + </listitem> + + <listitem> + <para> + When you <emphasis>add</emphasis> a cloud VM based on an + existing &oci; instance you can only change the display + name. + </para> + </listitem> + + </itemizedlist> + + </sect3> + + <sect3 id="cloud-vm-control"> + + <title>Controlling a Cloud VM</title> + + <para> + You can use &vbox-mgr; to control a cloud VM as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Start.</emphasis> Use the + <emphasis role="bold">Start</emphasis> button in the + &vbox-mgr; toolbar. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Stop.</emphasis> Right-click on the + cloud VM name, to display the + <emphasis role="bold">Close</emphasis> menu. Options to + shut down and power off the cloud VM are available. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Terminate.</emphasis> Use the + <emphasis role="bold">Terminate</emphasis> button in the + &vbox-mgr; toolbar. + </para> + + <caution> + <para> + This action deletes the instance from &oci;. + </para> + </caution> + </listitem> + + </itemizedlist> + + <para> + When you control a cloud VM in &vbox-mgr; the machine list is + updated automatically with the current instance state, such as + <emphasis role="bold">Stopped</emphasis> or + <emphasis role="bold">Running</emphasis>. + </para> + + <para> + When you control an instance using the &oci; console, + &vbox-mgr; updates the status for the corresponding cloud VM + automatically. + </para> + + </sect3> + + <sect3 id="cloud-vm-remove"> + + <title>Removing a Cloud VM</title> + + <para> + You can use &vbox-mgr; to remove a cloud VM as follows: + </para> + + <para> + Right-click on the cloud VM name and select + <emphasis role="bold">Remove</emphasis>. + </para> + + <itemizedlist> + + <listitem> + <para> + Click <emphasis role="bold">Remove Only</emphasis> to + remove the cloud VM from the machine list in VirtualBox + Manager. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Delete Everything</emphasis> + to remove the cloud VM from &vbox-mgr; and also to delete + the &oci; instance and any associated boot volumes. + </para> + </listitem> + + </itemizedlist> + + </sect3> + + <sect3 id="cloud-vm-instance-console"> + + <title>Creating an Instance Console Connection for a Cloud VM</title> + + <para> + To create a instance console connection, the cloud VM must be + in <emphasis role="bold">Running</emphasis> state. + </para> + + <orderedlist> + + <listitem> + <para> + Right-click on the cloud VM name and select + <emphasis role="bold">Console</emphasis>, + <emphasis role="bold">Create Connection</emphasis>. + </para> + </listitem> + + <listitem> + <para> + The <emphasis role="bold">Public Key</emphasis> dialog is + displayed. Paste the public key used for the instance + connection into the dialog and click + <emphasis role="bold">OK</emphasis>. + </para> + + <para> + By default, either the first entry in your SSH keys folder + or the public key used for your previous instance console + connection is used. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Connect</emphasis> to connect + to the instance. An instance console is displayed + automatically on the host. + </para> + </listitem> + + <listitem> + <para> + (Optional) Click <emphasis role="bold">Show Log</emphasis> + to display log messages for the instance console + connection. + </para> + </listitem> + + </orderedlist> + + <para> + See the &oci; documentation for details about how you can use + an instance console connection to troubleshoot instance + problems. + </para> + + </sect3> + + </sect2> + + <sect2 id="cloud-export-oci"> + + <title>Exporting an Appliance to &oci;</title> + + <para> + &product-name; supports the export of VMs to an &oci; service. + The exported VM is stored on &oci; as a custom Linux image. You + can configure whether a cloud instance is created and started + after the export process has completed. + </para> + + <note> + <para> + Before you export a VM to &oci;, you must prepare the VM as + described in <xref linkend="cloud-export-oci-prepare-vm"/>. + </para> + </note> + + <para> + Use the following steps to export a VM to &oci;: + </para> + + <orderedlist> + + <listitem> + <para> + Select <emphasis role="bold">File</emphasis>, + <emphasis role="bold">Export Appliance</emphasis> to open + the <emphasis role="bold">Export Virtual + Appliance</emphasis> wizard. + </para> + + <para> + Select a VM to export and click + <emphasis role="bold">Next</emphasis> to display the + <emphasis role="bold">Format Settings</emphasis> page. + </para> + </listitem> + + <listitem> + <para> + From the <emphasis role="bold">Format</emphasis> drop-down + list, select <emphasis role="bold">&oci;</emphasis>. + </para> + + <para> + In the <emphasis role="bold">Profile</emphasis> drop-down + list, select the cloud profile used for your &oci; account. + </para> + + <figure id="fig-export-appliance-oci"> + <title>Export Virtual Appliance Wizard: Format Settings</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/export-appliance-oci.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + In the <emphasis role="bold">Machine Creation</emphasis> + field, select an option to configure settings for the cloud + instance created when you export to &oci;. The options + enable you to do one of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Configure settings for the cloud instance + <emphasis>after</emphasis> you have finished exporting + the VM. + </para> + </listitem> + + <listitem> + <para> + Configure settings for the cloud instance + <emphasis>before</emphasis> you start to export the VM. + </para> + </listitem> + + <listitem> + <para> + Do not create a cloud instance when you export the VM. + </para> + </listitem> + + </itemizedlist> + + <para> + Click <emphasis role="bold">Next</emphasis> to make an API + request to the &oci; service and open the + <emphasis role="bold">Appliance Settings</emphasis> page. + </para> + </listitem> + + <listitem> + <para> + (Optional) Edit storage settings used for the exported + virtual machine in &oci;. You can change the following + settings: + </para> + + <itemizedlist> + + <listitem> + <para> + The name of the bucket used to store the exported files. + </para> + </listitem> + + <listitem> + <para> + Whether to store the custom image in &oci;. + </para> + </listitem> + + <listitem> + <para> + The display name for the custom image in &oci;. + </para> + </listitem> + + <listitem> + <para> + The launch mode for the custom image. + </para> + + <para> + <emphasis role="bold">Paravirtualized</emphasis> mode + gives improved performance and should be suitable for + most &product-name; VMs. + </para> + + <para> + <emphasis role="bold">Emulated</emphasis> mode is + suitable for legacy OS images. + </para> + </listitem> + + </itemizedlist> + + <para> + Click <emphasis role="bold">Finish</emphasis> to continue. + </para> + </listitem> + + <listitem> + <para> + (Optional) Depending on the selection in the + <emphasis role="bold">Machine Creation</emphasis> field, the + <emphasis role="bold">Appliance Settings</emphasis> page may + be displayed before or after export. This screen enables you + to configure settings for the cloud instance, such as Shape + and Disk Size. + </para> + + <para> + Click <emphasis role="bold">Finish</emphasis>. The VM is + exported to &oci;. + </para> + + <para> + Depending on the <emphasis role="bold">Machine + Creation</emphasis> setting, a cloud instance may be started + after upload to &oci; is completed. + </para> + </listitem> + + <listitem> + <para> + Monitor the export process by using the &oci; Console. + </para> + </listitem> + + </orderedlist> + + <para> + You can also use the <command>VBoxManage export</command> + command to export a VM to &oci;. See + <xref linkend="vboxmanage-export-cloud"/>. + </para> + + <sect3 id="cloud-export-oci-prepare-vm"> + + <title>Preparing a VM for Export to &oci;</title> + + <para> + &oci; provides the option to import a custom Linux image. + Before an &product-name; image can be exported to &oci;, the + custom image needs to be prepared to ensure that instances + launched from the custom image can boot correctly and that + network connections will work. This section provides advice on + how to prepare a Linux image for export from &product-name;. + </para> + + <para> + The following list shows some tasks to consider when preparing + an Oracle Linux VM for export: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Use DHCP for network + addresses.</emphasis> Configure the VM to use a DHCP + server to allocate network addresses, rather than using a + static IP address. The &oci; instance will then be + allocated an IP address automatically. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Do not specify a MAC + address.</emphasis> The network interface configuration + for the VM must not specify the MAC address. + </para> + + <para> + Remove the HWADDR setting from the + <filename>/etc/sysconfig/ifcfg-<replaceable>devicename</replaceable></filename> + network script. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Disable persistent network device + naming rules.</emphasis> This means that the &oci; + instance will use the same network device names as the VM. + </para> + + <orderedlist> + + <listitem> + <para> + Change the GRUB kernel parameters. + </para> + + <para> + Add <literal>net.ifnames=0</literal> and + <literal>biosdevname=0</literal> as kernel parameter + values to the <literal>GRUB_CMDLINE_LINUX</literal> + variable. + </para> + </listitem> + + <listitem> + <para> + Update the GRUB configuration. + </para> + +<screen># grub2-mkconfig -o /boot/grub2/grub.cfg</screen> + </listitem> + + <listitem> + <para> + Disable any <literal>udev</literal> rules for network + device naming. + </para> + + <para> + For example, if an automated <literal>udev</literal> + rule exists for <literal>net-persistence</literal>: + </para> + +<screen># cd /etc/udev/rules.d +# rm -f 70-persistent-net.rules +# ln -s /dev/null /etc/udev/rules.d/70-persistent-net.rules</screen> + </listitem> + + </orderedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable the serial + console.</emphasis> This enables you to troubleshoot the + instance when it is running on &oci;. + </para> + + <orderedlist> + + <listitem> + <para> + Edit the <filename>/etc/default/grub</filename> file, + as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + Remove the <literal>resume</literal> setting from + the kernel parameters. This setting slows down + boot time significantly. + </para> + </listitem> + + <listitem> + <para> + Replace <literal>GRUB_TERMINAL="gfxterm"</literal> + with <literal>GRUB_TERMINAL="console + serial"</literal>. This configures use of the + serial console instead of a graphical terminal. + </para> + </listitem> + + <listitem> + <para> + Add <literal>GRUB_SERIAL_COMMAND="serial --unit=0 + --speed=115200"</literal>. This configures the + serial connection. + </para> + </listitem> + + <listitem> + <para> + Add <literal>console=tty0 + console=ttyS0,115200</literal> to the + <literal>GRUB_CMDLINE_LINUX</literal> variable. + This adds the serial console to the Linux kernel + boot parameters. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Regenerate the GRUB configuration. + </para> + +<screen># grub2-mkconfig -o /boot/grub2/grub.cfg</screen> + </listitem> + + <listitem> + <para> + To verify the changes, reboot the machine and run the + <command>dmesg</command> command to look for the + updated kernel parameters. + </para> + +<screen># dmesg |grep console=ttyS0</screen> + </listitem> + + </orderedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable paravirtualized device + support.</emphasis> You do this by adding the + <literal>virtio</literal> drivers to the + <literal>initrd</literal> for the VM. + </para> + + <orderedlist> + + <listitem> + <para> + This procedure works only on machines with a Linux + kernel of version 3.4 or later. Check that the VM is + running a supported kernel: + </para> + +<screen># uname -a</screen> + </listitem> + + <listitem> + <para> + Use the <literal>dracut</literal> tool to rebuild + <literal>initrd</literal>. Add the + <literal>qemu</literal> module, as follows: + </para> + +<screen># dracut –-logfile /var/log/Dracut.log --force --add qemu</screen> + </listitem> + + <listitem> + <para> + Verify that the <literal>virtio</literal> drivers are + now present in <literal>initrd</literal>. + </para> + +<screen> # lsinitrd |grep virtio</screen> + </listitem> + + </orderedlist> + </listitem> + + </itemizedlist> + + <para> + For more information about importing a custom Linux image into + &oci;, see also: + </para> + + <para> + <ulink url="https://docs.cloud.oracle.com/iaas/Content/Compute/Tasks/importingcustomimagelinux.htm" /> + </para> + + </sect3> + + </sect2> + + <sect2 id="cloud-import-oci"> + + <title>Importing an Instance from &oci;</title> + + <para> + Perform the following steps to import a cloud instance from + &oci; into &product-name;: + </para> + + <orderedlist> + + <listitem> + <para> + Select <emphasis role="bold">File</emphasis>, + <emphasis role="bold">Import Appliance</emphasis> to open + the <emphasis role="bold">Import Virtual + Appliance</emphasis> wizard. + </para> + + <para> + In the <emphasis role="bold">Source</emphasis> drop-down + list, select <emphasis role="bold">&oci;</emphasis>. + </para> + + <para> + In the <emphasis role="bold">Profile</emphasis> drop-down + list, select the cloud profile for your &oci; account. + </para> + + <para> + Choose the required cloud instance from the list in the + <emphasis role="bold">Machines</emphasis> field. + </para> + + <para> + Click <emphasis role="bold">Next</emphasis> to make an API + request to the &oci; service and display the + <emphasis role="bold">Appliance Settings</emphasis> page. + </para> + </listitem> + + <listitem> + <para> + (Optional) Edit settings for the new local virtual machine. + </para> + + <para> + For example, you can edit the VM name and description. + </para> + + <figure id="fig-import-instance-oci"> + <title>Import Cloud Instance Wizard: Appliance Settings</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/import-instance.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + Click <emphasis role="bold">Finish</emphasis> to import the + instance from &oci;. + </para> + </listitem> + + <listitem> + <para> + Monitor the import process by using the &oci; Console. + </para> + </listitem> + + </orderedlist> + + <para> + You can also use the <command>VBoxManage import</command> + command to import an instance from &oci;. See + <xref linkend="vboxmanage-import-cloud"/>. + </para> + + <simplesect id="import-instance-sequence"> + + <title>Importing an Instance: Overview of Events</title> + + <para> + The following describes the sequence of events when you import + an instance from &oci;. + </para> + + <itemizedlist> + + <listitem> + <para> + A custom image is created from the boot volume of the + instance. + </para> + </listitem> + + <listitem> + <para> + The custom image is exported to an &oci; object and is + stored using Object Storage in the bucket specified by the + user. + </para> + </listitem> + + <listitem> + <para> + The &oci; object is downloaded to the local host. The + object is a TAR archive which contains a boot volume of + the instance in QCOW2 format and a JSON file containing + metadata related to the instance. + </para> + </listitem> + + <listitem> + <para> + The boot volume of the instance is extracted from the + archive and a new VMDK image is created by converting the + boot volume into the VMDK format. The VMDK image is + registered with &product-name;. + </para> + </listitem> + + <listitem> + <para> + A new VM is created using the VMDK image for the cloud + instance. + </para> + + <para> + By default, the new VM is not started after import from + &oci;. + </para> + </listitem> + + <listitem> + <para> + The downloaded TAR archive is deleted after a successful + import. + </para> + </listitem> + + </itemizedlist> + + </simplesect> + + </sect2> + + <sect2 id="cloud-using-cloud-networks"> + + <title>Using a Cloud Network</title> + + <para> + A cloud network is a type of network that can be used for + connections from a local VM to a remote &oci; cloud instance. + </para> + + <para> + To create and use a cloud network, do the following: + </para> + + <orderedlist> + + <listitem> + <para> + Set up a virtual cloud network on &oci;. + </para> + + <para> + The following steps create and configure a virtual cloud + network (VCN) on &oci;. The VCN is used to tunnel network + traffic across the cloud. + </para> + + <orderedlist> + + <listitem> + <para> + Ensure that you have a cloud profile for connecting to + &oci;. See <xref linkend="cloud-create-cloud-profile"/>. + </para> + </listitem> + + <listitem> + <para> + Run the following <command>VBoxManage cloud</command> + command: + </para> + +<screen>VBoxManage cloud --provider="OCI" --profile="vbox-oci" network setup</screen> + + <para> + where <literal>vbox-oci</literal> is the name of your + cloud profile. + </para> + + <para> + Other options are available for the <command>VBoxManage + cloud network setup</command> command, to enable you to + configure details for the VCN. For example, you can + configure the operating system used for the cloud + gateway instance and the IP address range used by the + tunneling network. See + <xref linkend="vboxmanage-cloud"/>. + </para> + + <para> + For best results, use an Oracle Linux 7 instance for the + cloud gateway. This is the default option. + </para> + </listitem> + + </orderedlist> + </listitem> + + <listitem> + <para> + Register the new cloud network with &product-name;. + </para> + + <para> + Use the <emphasis role="bold">Cloud Networks</emphasis> tab + in the <emphasis role="bold">Network Manager</emphasis> + tool. See + <xref linkend="network-manager-cloud-network-tab"/>. + </para> + </listitem> + + <listitem> + <para> + Add cloud network adaptors to the local VMs that will use + the cloud network. See <xref linkend="network_cloud"/>. + </para> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="cloud-using-cli"> + + <title>Using VBoxManage Commands With &oci;</title> + + <para> + This section includes some examples of how + <command>VBoxManage</command> commands can be used to integrate + with &oci; and perform common cloud operations. + </para> + + <para> + <emphasis role="bold">Creating a Cloud Profile</emphasis> + </para> + + <para> + To create a cloud profile called <literal>vbox-oci</literal>: + </para> + +<screen>VBoxManage cloudprofile --provider "OCI" --profile="vbox-oci" add \ +--clouduser="ocid1.user.oc1..." --keyfile="/home/username/.oci/oci_api_key.pem" \ +--tenancy="ocid1.tenancy.oc1..." --compartment="ocid1.compartment.oc1..." --region="us-ashburn-1" +</screen> + + <para> + The new cloud profile is added to the + <filename>oci_config</filename> file in your &product-name; + global configuration directory. For example, this is + <filename>$HOME/.VirtualBox/oci_config</filename> on a Windows + host. + </para> + + <para> + <emphasis role="bold">Listing Cloud Instances</emphasis> + </para> + + <para> + To list the instances in your &oci; compartment: + </para> + +<screen>VBoxManage cloud --provider="OCI" --profile="vbox-oci" list instances +</screen> + + <para> + <emphasis role="bold">Exporting an &product-name; VM to the + Cloud</emphasis> + </para> + + <para> + To export a VM called <literal>myVM</literal> and create a cloud + instance called <literal>myVM_Cloud</literal>: + </para> + +<screen>VBoxManage export myVM --output OCI:// --cloud 0 --vmname myVM_Cloud \ +--cloudprofile "vbox-oci" --cloudbucket myBucket \ +--cloudshape VM.Standard2.1 --clouddomain US-ASHBURN-AD-1 --clouddisksize 50 \ +--cloudocivcn ocid1.vcn.oc1... --cloudocisubnet ocid1.subnet.oc1... \ +--cloudkeepobject true --cloudlaunchinstance true --cloudpublicip true + </screen> + + <para> + <emphasis role="bold">Importing a Cloud Instance Into + &product-name;</emphasis> + </para> + + <para> + To import a cloud instance and create an &product-name; VM + called <literal>oci_Import</literal>: + </para> + +<screen>VBoxManage import OCI:// --cloud --vmname oci_Import --memory 4000 +--cpus 3 --ostype FreeBSD_64 --cloudprofile "vbox-oci" +--cloudinstanceid ocid1.instance.oc1... --cloudbucket myBucket + </screen> + + <para> + <emphasis role="bold">Creating a New Cloud Instance From a + Custom Image</emphasis> + </para> + + <para> + To create a new cloud instance from a custom image on &oci;: + </para> + +<screen>VBoxManage cloud --provider="OCI" --profile="vbox-oci" instance create \ +--domain-name="oraclecloud.com" --image-id="ocid1.image.oc1..." --display-name="myInstance" \ +--shape="VM.Standard2.1" --subnet="ocid1.subnet.oc1..."</screen> + + <para> + <emphasis role="bold">Terminating a Cloud Instance</emphasis> + </para> + + <para> + To terminate an instance in your compartment on &oci;: + </para> + +<screen>VBoxManage cloud --provider="OCI" --profile="vbox-oci" instance terminate \ +--id="ocid1.instance.oc1..." </screen> + + <para> + For more details about the available commands for cloud + operations, see <xref linkend="vboxmanage-cloud"/>. + </para> + + </sect2> + + </sect1> + + <sect1 id="preferences"> + + <title>Preferences</title> + + <para> + The Preferences window offers a selection of settings, which apply + to all virtual machines of the current user. + </para> + + <para> + To display the Preferences window, do either of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Select <emphasis role="bold">File</emphasis>, + <emphasis role="bold">Preferences</emphasis>. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Preferences</emphasis> on the + Welcome screen in &vbox-mgr;. + </para> + </listitem> + + </itemizedlist> + + <para> + The following settings are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">General.</emphasis> Enables you to + specify the default folder or directory for VM files, and the + VRDP Authentication Library. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Input.</emphasis> Enables you to specify + keyboard shortcuts, such as the <emphasis role="bold">Host + key</emphasis>. This is the key that toggles whether the + cursor is in the focus of the VM or the Host OS windows, see + <xref linkend="keyb_mouse_normal"/>. The Host key is also used + to trigger certain VM actions, see + <xref linkend="specialcharacters"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Update.</emphasis> Enables you to + specify various settings for Automatic Updates. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Language.</emphasis> Enables you to + specify the language used for menus, labels, and text in + &vbox-mgr;. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Display.</emphasis> Enables you to + specify the screen resolution, and its width and height. A + default scale factor can be specified for all guest screens. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Proxy.</emphasis> Enables you to + configure an HTTP Proxy Server. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Interface.</emphasis> Enables you to + select a color theme for the &vbox-mgr; user interface. + </para> + + <note> + <para> + This setting is only available on Windows host platforms. + </para> + </note> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="frontends"> + + <title>Alternative Front-Ends</title> + + <para> + As briefly mentioned in <xref linkend="features-overview" />, + &product-name; has a very flexible internal design that enables + you to use multiple interfaces to control the same virtual + machines. For example, you can start a virtual machine with the + &vbox-mgr; window and then stop it from the command line. With + &product-name;'s support for the Remote Desktop Protocol (RDP), + you can even run virtual machines remotely on a headless server + and have all the graphical output redirected over the network. + </para> + + <para> + The following front-ends are shipped in the standard + &product-name; package: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">VirtualBox.</emphasis> This is the + &vbox-mgr;, a graphical user interface that uses the Qt + toolkit. This interface is described throughout this manual. + While this is the simplest and easiest front-end to use, some + of the more advanced &product-name; features are not included. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VBoxManage.</emphasis> A command-line + interface for automated and detailed control of every aspect + of &product-name;. See + <xref + linkend="vboxmanage" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VBoxHeadless.</emphasis> A front-end + that produces no visible output on the host at all, but can + act as a RDP server if the VirtualBox Remote Desktop Extension + (VRDE) is installed and enabled for the VM. As opposed to the + other graphical interfaces, the headless front-end requires no + graphics support. This is useful, for example, if you want to + host your virtual machines on a headless Linux server that has + no X Window system installed. See + <xref linkend="vboxheadless" />. + </para> + </listitem> + + </itemizedlist> + + <para> + If the above front-ends still do not satisfy your particular + needs, it is possible to create yet another front-end to the + complex virtualization engine that is the core of &product-name;, + as the &product-name; core neatly exposes all of its features in a + clean API. See <xref linkend="VirtualBoxAPI" />. + </para> + + </sect1> + + <sect1 id="soft-keyb"> + + <title>Soft Keyboard</title> + + <para> + &product-name; provides a <emphasis>soft keyboard</emphasis> that + enables you to input keyboard characters on the guest. A soft + keyboard is an on-screen keyboard that can be used as an + alternative to a physical keyboard. See + <xref linkend="soft-keyb-using"/> for details of how to use the + soft keyboard. + </para> + + <caution> + <para> + For best results, ensure that the keyboard layout configured on + the guest OS matches the keyboard layout used by the soft + keyboard. &product-name; does not do this automatically. + </para> + </caution> + + <figure id="fig-soft-keyb"> + <title>Soft Keyboard in a Guest Virtual Machine</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/softkeybd.png" + width="14cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The soft keyboard can be used in the following scenarios: + </para> + + <itemizedlist> + + <listitem> + <para> + When the physical keyboard on the host is not the same as the + keyboard layout configured on the guest. For example, if the + guest is configured to use an international keyboard, but the + host keyboard is US English. + </para> + </listitem> + + <listitem> + <para> + To send special key combinations to the guest. Note that some + common key combinations are also available in the + <emphasis role="bold">Input</emphasis>, + <emphasis role="bold">Keyboard</emphasis> menu of the guest VM + window. See <xref linkend="specialcharacters"/>. + </para> + </listitem> + + <listitem> + <para> + For guests in kiosk mode, where a physical keyboard is not + present. + </para> + </listitem> + + <listitem> + <para> + When using nested virtualization, the soft keyboard provides a + method of sending key presses to a guest. + </para> + </listitem> + + </itemizedlist> + + <para> + By default, the soft keyboard includes some common international + keyboard layouts. You can copy and modify these to meet your own + requirements. See <xref linkend="soft-keyb-custom"/>. + </para> + + <sect2 id="soft-keyb-using"> + + <title>Using the Soft Keyboard</title> + + <orderedlist> + + <listitem> + <para> + Display the soft keyboard. + </para> + + <para> + In the guest VM window, select + <emphasis role="bold">Input</emphasis>, + <emphasis role="bold">Keyboard</emphasis>, + <emphasis role="bold">Soft Keyboard</emphasis>. + </para> + </listitem> + + <listitem> + <para> + Select the required keyboard layout. + </para> + + <para> + The name of the current keyboard layout is displayed in the + toolbar of the soft keyboard window. This is the previous + keyboard layout that was used. + </para> + + <para> + Click the <emphasis role="bold">Layout List</emphasis> icon + in the toolbar of the soft keyboard window. The + <emphasis role="bold">Layout List</emphasis> window is + displayed. + </para> + + <para> + Select the required keyboard layout from the entries in the + <emphasis role="bold">Layout List</emphasis> window. + </para> + + <para> + The keyboard display graphic is updated to show the + available input keys. + </para> + </listitem> + + <listitem> + <para> + Use the soft keyboard to enter keyboard characters on the + guest. + </para> + + <itemizedlist> + + <listitem> + <para> + Modifier keys such as Shift, Ctrl, and Alt are available + on the soft keyboard. Click once to select the modifier + key, click twice to lock the modifier key. + </para> + + <para> + The <emphasis role="bold">Reset the Keyboard and Release + All Keys</emphasis> icon can be used to release all + pressed modifier keys, both on the host and the guest. + </para> + </listitem> + + <listitem> + <para> + To change the look of the soft keyboard, click the + <emphasis role="bold">Settings</emphasis> icon in the + toolbar. You can change colors used in the keyboard + graphic, and can hide or show sections of the keyboard, + such as the NumPad or multimedia keys. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="soft-keyb-custom"> + + <title>Creating a Custom Keyboard Layout</title> + + <para> + You can use one of the supplied default keyboard layouts as the + starting point to create a custom keyboard layout. + </para> + + <note> + <para> + To permananently save a custom keyboard layout, you must save + it to a file. Otherwise, any changes you make are discarded + when you close down the <emphasis role="bold">Soft + Keyboard</emphasis> window. + </para> + + <para> + Custom keyboard layouts that you save are stored as an XML + file on the host, in the <filename>keyboardLayouts</filename> + folder in the global configuration data directory. For + example, in + <filename>$HOME/.config/VirtualBox/keyboardLayouts</filename> + on a Linux host. + </para> + </note> + + <orderedlist> + + <listitem> + <para> + Display the <emphasis role="bold">Layout List</emphasis>. + </para> + + <para> + Click the <emphasis role="bold">Layout List</emphasis> icon + in the toolbar of the soft keyboard window. + </para> + </listitem> + + <listitem> + <para> + Make a copy of an existing keyboard layout. + </para> + + <para> + Highlight the required layout and click the + <emphasis role="bold">Copy the Selected Layout</emphasis> + icon. + </para> + + <para> + A new layout entry with a name suffix of + <literal>-Copy</literal> is created. + </para> + </listitem> + + <listitem> + <para> + Edit the new keyboard layout. + </para> + + <para> + Highlight the new layout in the <emphasis role="bold">Layout + List</emphasis> and click the <emphasis role="bold">Edit the + Selected Layout</emphasis> icon. + </para> + + <para> + Enter a new name for the layout. + </para> + + <para> + Edit keys in the new layout. Click on the key that you want + to edit and enter new key captions in the + <emphasis role="bold">Captions</emphasis> fields. + </para> + + <para> + The keyboard graphic is updated with the new captions. + </para> + </listitem> + + <listitem> + <para> + (Optional) Save the layout to a file. This means that your + custom keyboard layout will be available for future use. + </para> + + <para> + Highlight the new layout in the <emphasis role="bold">Layout + List</emphasis> and click the <emphasis role="bold">Save the + Selected Layout into File</emphasis> icon. + </para> + + <para> + Any custom layouts that you create can later be removed from + the Layout List, by highlighting and clicking the + <emphasis role="bold">Delete the Selected Layout</emphasis> + icon. + </para> + </listitem> + + </orderedlist> + + </sect2> + + </sect1> + + <sect1 id="vm-info"> + + <title>Monitoring of Virtual Machines</title> + + <para> + &vbox-mgr; includes the following tools for viewing runtime + information and changing the configuration of virtual machines. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold"> VM Activity Overview.</emphasis> + Displays an overview of performance metrics for all running + VMs. + </para> + + <para> + See <xref linkend="vm-activity-overview"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Session Information Dialog.</emphasis> + Displays configuration and runtime information for the + selected guest system. + </para> + + <para> + See <xref linkend="vm-activity-session-information"/> + </para> + </listitem> + + </itemizedlist> + + <sect2 id="vm-activity-overview"> + + <title>VM Activity Overview</title> + + <para> + The VM Activity Overview tool displays several performance + metrics for all running virtual machines and for the host + system. This provides an overview of system resources used by + individual virtual machines and the host system. + </para> + + <para> + To display the VM Activity Overview tool, do the following: + </para> + + <para> + Go to the global <emphasis role="bold">Tools</emphasis> menu and + click <emphasis role="bold">Activities</emphasis>. The + <emphasis role="bold">VM Activity Overview</emphasis> window is + shown. + </para> + + <figure id="fig-vm-activity-overview-widget"> + <title>VM Activity Overview Tool</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/vm-activity-overview.png" + width="14cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + To show metrics for <emphasis>all</emphasis> virtual machines, + including those that are not running, right-click on the list of + virtual machines and select <emphasis role="bold">List All + Virtual Machines</emphasis>. + </para> + + <para> + To configure the set of metrics to be shown, click + <emphasis role="bold">Columns</emphasis> in the toolbar. You can + then sort the list of virtual machines by a particular metric. + </para> + + <para> + To see more performance information for a virtual machine, + select the VM name and click <emphasis role="bold">VM + Activity</emphasis> in the toolbar. The <emphasis role="bold">VM + Activity</emphasis> tab of the <emphasis role="bold">Session + Information</emphasis> dialog is shown, see + <xref linkend="vm-activity-session-information"/>. + </para> + + </sect2> + + <sect2 id="vm-activity-session-information"> + + <title>Session Information Dialog</title> + + <para> + The Session Information dialog includes multiple tabs which show + important configuration and runtime information for the guest + system. The tabs of the dialog are as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Configuration Details.</emphasis> + Displays the system configuration of the virtual machine in + a tabular format. The displayed information includes details + such as storage configuration and audio settings. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Runtime Information.</emphasis> + Displays runtime information for the guest session in a + tabular format similar to the Configuration Details tab. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VM Activity.</emphasis> Includes + several time series charts which monitor guest resource + usage including CPU, RAM, Disk I/O, and Network. Note that + the RAM chart requires the Guest Additions to be running on + the guest system. The VM Activity tab can also be accessed + directly from the VM Activity Overview tool. See + <xref linkend="vm-activity-overview"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Guest Control</emphasis>. Details of + processes used by the Guest Control File Manager. See + <xref linkend="guestadd-gc-file-manager"/>. + </para> + </listitem> + + </itemizedlist> + + <para> + To display the Session Information dialog, select + <emphasis role="bold">Machine</emphasis>, + <emphasis role="bold">Session Information</emphasis> in the + guest VM. + </para> + + <figure id="fig-vm-session-information"> + <title>Session Information Dialog, Showing VM Activity Tab</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/session-information.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + </sect2> + + </sect1> + + <sect1 id="log-viewer"> + + <title>The Log Viewer</title> + + <para> + Every time you start up a VM, &product-name; creates a log file + that records system configuration and events. The + <emphasis role="bold">Log Viewer</emphasis> is a &vbox-mgr; tool + that enables you to view and analyze system logs. + </para> + + <figure id="fig-log-viewer-tool"> + <title>Log Viewer Tool, Showing System Events</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/log-viewer.png" + width="10cm" /> + </imageobject> + </mediaobject> + + </figure> + + <para> + To display the Log Viewer, do either of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Click the VM name in the machine list and select + <emphasis role="bold">Logs</emphasis> from the machine tools + menu. + </para> + </listitem> + + <listitem> + <para> + In the guest VM, select + <emphasis role="bold">Machine</emphasis>, + <emphasis role="bold">Show Log</emphasis>. + </para> + </listitem> + + </itemizedlist> + + <para> + Log messages for the VM are displayed in tabs in the Log Viewer + window. See <xref linkend="collect-debug-info"/> for details of + the various log files generated by &product-name;. + </para> + + <para> + If you select multiple VMs in the machine list, logs are listed + for each VM. + </para> + + <para> + The toolbar of the Log Viewer includes the following options: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Save:</emphasis> Exports the contents of + the selected log file to a text file. Specify the destination + filename and location in the displayed dialog. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Find:</emphasis> Searches for a text + string in the log file. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Filter:</emphasis> Uses filter terms to + display specific types of log messages. Common log message + terms used by &product-name;, such as Audio and NAT, are + included by default. Select one or more terms from the + drop-down list. To add your own filter term, enter the text + string in the text box field. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Bookmark:</emphasis> Saves the location + of a log message, enabling you to find it quickly. To create a + bookmark, either click on the line number, or select some text + and then click <emphasis role="bold">Bookmark</emphasis>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Options:</emphasis> Configures the text + display used in the log message window. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Refresh:</emphasis> Refreshes the log + file you are currently viewing. Only log messages in the + current tab are updated. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Reload:</emphasis> Refreshes all log + files. Log messages in every tab are updated. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Settings:</emphasis> Displays the + <emphasis role="bold">Settings</emphasis> window for the VM, + enabling you to make configuration changes. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Discard:</emphasis> For a running VM, + discards the saved state for the VM and closes it down. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Show/Start:</emphasis> For a running VM, + <emphasis role="bold">Show</emphasis> displays the VM window. + For a stopped VM, <emphasis role="bold">Start</emphasis> + displays options for powering up the VM. + </para> + </listitem> + + </itemizedlist> + + </sect1> + +</chapter> diff --git a/doc/manual/en_US/user_KnownIssues.xml b/doc/manual/en_US/user_KnownIssues.xml new file mode 100644 index 00000000..564cbe30 --- /dev/null +++ b/doc/manual/en_US/user_KnownIssues.xml @@ -0,0 +1,502 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="KnownIssues"> + + <title>Known Limitations</title> + + <sect1 id="ExperimentalFeatures"> + + <title>Experimental Features</title> + + <para> + Some &product-name; features are labeled as experimental. Such + features are provided on an "as-is" basis and are not formally + supported. However, feedback and suggestions about such features + are welcome. A comprehensive list of experimental features is as + follows: + </para> + + <itemizedlist> + + <listitem> + <para> + Hardware 3D acceleration support for Windows, Linux, and + Oracle Solaris guests + </para> + </listitem> + + <listitem> + <para> + Hardware 2D video playback acceleration support for Windows + guests + </para> + </listitem> + +<!-- <listitem> + <para> + PCI passthrough (Linux hosts only) + </para> + </listitem>--> + + <listitem> + <para> + Mac OS X guests (macOS hosts only) + </para> + </listitem> + + <listitem> + <para> + ICH9 chipset emulation + </para> + </listitem> + + <listitem> + <para> + EFI firmware + </para> + </listitem> + + <listitem> + <para> + Host CD/DVD drive passthrough + </para> + </listitem> + + <listitem> + <para> + Support of iSCSI using internal networking + </para> + </listitem> + + <listitem> + <para> + Using &product-name; and Hyper-V on the same host + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="KnownProblems"> + + <title>Known Issues</title> + + <para> + The following section describes known problems with this release + of &product-name;. Unless marked otherwise, these issues are + planned to be fixed in later releases. + </para> + + <itemizedlist> + + <listitem> + <para> + The macOS installer packages for &product-name; 7 currently do + not include the Internal Networking feature, which is + available on all other platforms. This will be addressed with + an update of &product-name; 7. For setups which depend on this + functionality it is best to keep using &product-name; 6.1. + </para> + </listitem> + + <listitem> + <para> + Poor performance when using &product-name; and + <emphasis role="bold">Hyper-V</emphasis> on the same host. To + fix this, certain Windows features like "Hyper-V Platform", + "Virtual Machine Platform" and "Windows Hypervisor Platform" + must be turned off, followed by a host reboot. + </para> + + <para> + Additionally, the Microsoft Device Guard and Credential Guard + hardware readiness tool might have to be used in order to turn + off more features. For example, by running the following + command: + </para> + +<screen>.\DG_Readiness_Tool_vX.X.ps1 -Disable -AutoReboot</screen> + + <note> + <para> + Disabling Device Guard and Credential Guard features will + have an impact on the overall security of the host. Please + contact your Administrator beforehand regarding this. + </para> + </note> + </listitem> + + <listitem> + <para> + The following <emphasis role="bold">Guest SMP (multiprocessor) + limitations</emphasis> exist: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Poor performance</emphasis> with + 32-bit guests on AMD CPUs. This affects mainly Windows and + Oracle Solaris guests, but possibly also some Linux kernel + revisions. Partially solved for 32-bit Windows NT, 2000, + XP, and 2003 guests. Requires the Guest Additions to be + installed. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Poor performance</emphasis> with + 32-bit guests on certain Intel CPU models that do not + include virtual APIC hardware optimization support. This + affects mainly Windows and Oracle Solaris guests, but + possibly also some Linux kernel revisions. Partially + solved for 32-bit Windows NT, 2000, XP, and 2003 guests. + Requires the Guest Additions to be installed. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">NX (no execute, data execution + prevention)</emphasis> only works for guests running on 64-bit + hosts and requires that hardware virtualization be enabled. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Guest control.</emphasis> On Windows + guests, a process started using the guest control execute + support will not be able to display a graphical user interface + <emphasis>unless</emphasis> the user account under which it is + running is currently logged in and has a desktop session. + </para> + + <para> + Also, to use accounts without or with an empty password, the + guest's group policy must be changed. To do so, open the group + policy editor on the command line by typing + <command>gpedit.msc</command>, open the key <literal>Computer + Configuration\Windows Settings\Security Settings\Local + Policies\Security Options</literal> and change the value of + <literal>Accounts: Limit local account use of blank passwords + to console logon only</literal> to Disabled. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Compacting virtual disk images is + limited to VDI files.</emphasis> The <command>VBoxManage + modifymedium --compact</command> command is currently only + implemented for VDI files. At the moment the only way to + optimize the size of a virtual disk images in other formats, + such as VMDK or VHD, is to clone the image and then use the + cloned image in the VM configuration. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">OVF import/export:</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + OVF localization, with multiple languages in a single OVF + file, is not yet supported. + </para> + </listitem> + + <listitem> + <para> + Some OVF sections like StartupSection, + DeploymentOptionSection, and InstallSection are ignored. + </para> + </listitem> + + <listitem> + <para> + OVF environment documents, including their property + sections and appliance configuration with ISO images, are + not yet supported. + </para> + </listitem> + + <listitem> + <para> + Remote files using HTTP or other mechanisms are not yet + supported. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Neither <emphasis role="bold">scale mode</emphasis> nor + <emphasis role="bold">seamless mode</emphasis> work correctly + with guests using OpenGL 3D features, such as with + Compiz-enabled window managers. + </para> + </listitem> + + <listitem> + <para> + The RDP server in the &product-name; extension pack supports + only audio streams in format 22.05kHz stereo 16-bit. If the + RDP client requests any other audio format there will be no + audio. + </para> + </listitem> + + <listitem> + <para> + Preserving the aspect ratio in scale mode works only on + Windows hosts and on macOS hosts. + </para> + </listitem> + + <listitem> + <para> + On <emphasis role="bold">macOS hosts</emphasis>, the following + features are not yet implemented: + </para> + + <itemizedlist> + + <listitem> + <para> + Numlock emulation + </para> + </listitem> + + <listitem> + <para> + CPU frequency metric + </para> + </listitem> + + <listitem> + <para> + Memory ballooning + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">macOS/ARM64 (Apple silicon) host + package</emphasis> + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Mac OS X guests:</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + Mac OS X guests can only run on a certain host hardware. + For details about license and host hardware limitations. + See <xref linkend="intro-macosxguests" /> and check the + Apple software license conditions. + </para> + </listitem> + + <listitem> + <para> + &product-name; does not provide Guest Additions for Mac OS + X at this time. + </para> + </listitem> + + <listitem> + <para> + The graphics resolution currently defaults to 1024x768 as + Mac OS X falls back to the built-in EFI display support. + See <xref linkend="efividmode" /> for more information on + how to change EFI video modes. + </para> + </listitem> + + <listitem> + <para> + Mac OS X guests only work with one CPU assigned to the VM. + Support for SMP will be provided in a future release. + </para> + </listitem> + + <listitem> + <para> + Depending on your system and version of Mac OS X, you + might experience guest hangs after some time. This can be + fixed by turning off energy saving. Set the timeout to + "Never" in the system preferences. + </para> + </listitem> + + <listitem> + <para> + By default, the &product-name; EFI enables debug output of + the Mac OS X kernel to help you diagnose boot problems. + Note that there is a lot of output and not all errors are + fatal. They would also show when using a physical Apple + Macintosh computer. You can turn off these messages by + using the following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal2/EfiBootArgs" " "</screen> + + <para> + To revert to the previous behavior, use the following + command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal2/EfiBootArgs" ""</screen> + </listitem> + + <listitem> + <para> + It is currently not possible to start a Mac OS X guest in + safe mode by specifying the <option>-x</option> option in + <literal>VBoxInternal2/EfiBootArgs</literal> extradata. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Oracle Solaris hosts:</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + USB support on Oracle Solaris hosts requires Oracle + Solaris 11 version snv_124 or later. Webcams and other + isochronous devices are known to have poor performance. + </para> + </listitem> + + <listitem> + <para> + Host Webcam passthrough is restricted to 640x480 frames at + 20 frames per second due to limitations in the Oracle + Solaris V4L2 API. This may be addressed in a future Oracle + Solaris release. + </para> + </listitem> + + <listitem> + <para> + No ACPI information, such as battery status or power + source, is reported to the guest. + </para> + </listitem> + + <listitem> + <para> + No support for using wireless adapters with bridged + networking. + </para> + </listitem> + + <listitem> + <para> + Crossbow-based bridged networking on Oracle Solaris 11 + hosts does not work directly with aggregate links. + However, you can use <command>dladm</command> to manually + create a VNIC over the aggregate link and use that with a + VM. This limitation does not exist in Oracle Solaris 11u1 + build 17 and later. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Neither virtio nor Intel PRO/1000 drivers for + <emphasis role="bold">Windows XP guests</emphasis> support + segmentation offloading. Therefore Windows XP guests have + slower transmission rates comparing to other guest types. + Refer to MS Knowledge base article 842264 for additional + information. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Guest Additions for OS/2.</emphasis> + Seamless windows and automatic guest resizing will probably + never be implemented due to inherent limitations of the OS/2 + graphics system. + </para> + </listitem> + + <listitem> + <para> + Some guest operating systems predating ATAPI CD-ROMs may + exhibit long delays or entirely fail to boot in certain + configurations. This is most likely to happen when an + IDE/ATAPI CD-ROM exists alone on a primary or secondary IDE + channel. + </para> + + <para> + Affected operating systems are MS OS/2 1.21: fails to boot + with an error message referencing COUNTRY.SYS and MS OS/2 1.3: + long boot delays. To avoid such problems, disable the emulated + IDE/ATAPI CD-ROM. The guest OS cannot use this device, anyway. + </para> + </listitem> + + </itemizedlist> + + </sect1> + +</chapter> diff --git a/doc/manual/en_US/user_Networking.xml b/doc/manual/en_US/user_Networking.xml new file mode 100644 index 00000000..e2f267f8 --- /dev/null +++ b/doc/manual/en_US/user_Networking.xml @@ -0,0 +1,1944 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="networkingdetails"> + + <title>Virtual Networking</title> + + <para> + As mentioned in <xref linkend="settings-network" />, &product-name; + provides up to eight virtual PCI Ethernet cards for each virtual + machine. For each such card, you can individually select the + following: + </para> + + <itemizedlist> + + <listitem> + <para> + The hardware that will be virtualized. + </para> + </listitem> + + <listitem> + <para> + The virtualization mode that the virtual card operates in, with + respect to your physical networking hardware on the host. + </para> + </listitem> + + </itemizedlist> + + <para> + Four of the network cards can be configured in the + <emphasis role="bold">Network</emphasis> section of the + <emphasis role="bold">Settings</emphasis> window in &vbox-mgr;. You + can configure all eight network cards on the command line using + <command>VBoxManage modifyvm</command>. See + <xref linkend="vboxmanage-modifyvm" />. + </para> + + <para> + This chapter explains the various networking settings in more + detail. + </para> + + <sect1 id="nichardware"> + + <title>Virtual Networking Hardware</title> + + <para> + For each card, you can individually select what kind of + <emphasis>hardware</emphasis> will be presented to the virtual + machine. &product-name; can virtualize the following types of + networking hardware: + </para> + + <itemizedlist> + + <listitem> + <para> + AMD PCNet PCI II (Am79C970A) + </para> + </listitem> + + <listitem> + <para> + AMD PCNet FAST III (Am79C973), the default setting + </para> + </listitem> + + <listitem> + <para> + Intel PRO/1000 MT Desktop (82540EM) + </para> + </listitem> + + <listitem> + <para> + Intel PRO/1000 T Server (82543GC) + </para> + </listitem> + + <listitem> + <para> + Intel PRO/1000 MT Server (82545EM) + </para> + </listitem> + + <listitem> + <para> + Paravirtualized network adapter (virtio-net) + </para> + </listitem> + + </itemizedlist> + + <para> + The PCNet FAST III is the default because it is supported by + nearly all operating systems, as well as by the GNU GRUB boot + manager. As an exception, the Intel PRO/1000 family adapters are + chosen for some guest operating system types that no longer ship + with drivers for the PCNet card, such as Windows Vista. + </para> + + <para> + The Intel PRO/1000 MT Desktop type works with Windows Vista and + later versions. The T Server variant of the Intel PRO/1000 card is + recognized by Windows XP guests without additional driver + installation. The MT Server variant facilitates OVF imports from + other platforms. + </para> + + <para> + The Paravirtualized network adapter (virtio-net) is special. If + you select this adapter, then &product-name; does + <emphasis>not</emphasis> virtualize common networking hardware + that is supported by common guest operating systems. Instead, + &product-name; expects a special software interface for + virtualized environments to be provided by the guest, thus + avoiding the complexity of emulating networking hardware and + improving network performance. &product-name; provides support for + the industry-standard <emphasis>virtio</emphasis> networking + drivers, which are part of the open source KVM project. + </para> + + <para> + The virtio networking drivers are available for the following + guest operating systems: + </para> + + <itemizedlist> + + <listitem> + <para> + Linux kernels version 2.6.25 or later can be configured to + provide virtio support. Some distributions have also + back-ported virtio to older kernels. + </para> + </listitem> + + <listitem> + <para> + For Windows 2000, XP, and Vista, virtio drivers can be + downloaded and installed from the KVM project web page: + </para> + + <para> + <ulink + url="http://www.linux-kvm.org/page/WindowsGuestDrivers" />. + </para> + </listitem> + + </itemizedlist> + + <para> + &product-name; also has limited support for <emphasis>jumbo + frames</emphasis>. These are networking packets with more than + 1500 bytes of data, provided that you use the Intel card + virtualization and bridged networking. Jumbo frames are not + supported with the AMD networking devices. In those cases, jumbo + packets will silently be dropped for both the transmit and the + receive direction. Guest operating systems trying to use this + feature will observe this as a packet loss, which may lead to + unexpected application behavior in the guest. This does not cause + problems with guest operating systems in their default + configuration, as jumbo frames need to be explicitly enabled. + </para> + + </sect1> + + <sect1 id="networkingmodes"> + + <title>Introduction to Networking Modes</title> + + <para> + Each of the networking adapters can be separately configured to + operate in one of the following modes: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Not attached.</emphasis> In this mode, + &product-name; reports to the guest that a network card is + present, but that there is no connection. This is as if no + Ethernet cable was plugged into the card. Using this mode, it + is possible to <emphasis>pull</emphasis> the virtual Ethernet + cable and disrupt the connection, which can be useful to + inform a guest operating system that no network connection is + available and enforce a reconfiguration. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Network Address Translation + (NAT)</emphasis>. If all you want is to browse the Web, + download files, and view email inside the guest, then this + default mode should be sufficient for you, and you can skip + the rest of this section. Please note that there are certain + limitations when using Windows file sharing. See + <xref linkend="nat-limitations" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">NAT Network.</emphasis> A NAT network is + a type of internal network that allows outbound connections. + See <xref linkend="network_nat_service"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Bridged networking.</emphasis> This is + for more advanced networking needs, such as network + simulations and running servers in a guest. When enabled, + &product-name; connects to one of your installed network cards + and exchanges network packets directly, circumventing your + host operating system's network stack. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Internal networking.</emphasis> This can + be used to create a different kind of software-based network + which is visible to selected virtual machines, but not to + applications running on the host or to the outside world. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Host-only networking.</emphasis> This + can be used to create a network containing the host and a set + of virtual machines, without the need for the host's physical + network interface. Instead, a virtual network interface, + similar to a loopback interface, is created on the host, + providing connectivity among virtual machines and the host. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Cloud networking.</emphasis> This can be + used to connect a local VM to a subnet on a remote cloud + service. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold"> Generic networking.</emphasis> Rarely + used modes which share the same generic network interface, by + allowing the user to select a driver which can be included + with &product-name; or be distributed in an extension pack. + </para> + + <para> + The following sub-modes are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">UDP Tunnel:</emphasis> Used to + interconnect virtual machines running on different hosts + directly, easily, and transparently, over an existing + network infrastructure. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VDE (Virtual Distributed Ethernet) + networking:</emphasis> Used to connect to a Virtual + Distributed Ethernet switch on a Linux or a FreeBSD host. + At the moment this option requires compilation of + &product-name; from sources, as the Oracle packages do not + include it. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + + <para> + The following table provides an overview of the most important + networking modes. + </para> + + <table id="table-networking-modes" tabstyle="oracle-all"> + <title>Overview of Networking Modes</title> + <tgroup cols="6"> + <colspec align="left" /> + <colspec align="center" /> + <colspec align="center" /> + <colspec align="center" /> + <colspec align="center" /> + <colspec align="center" /> + <thead valign="middle"> + <row> + <entry><emphasis role="bold">Mode</emphasis></entry> + <entry><para> + <emphasis role="bold">VM→Host</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">VM←Host</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">VM1↔VM2</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">VM→Net/LAN</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">VM←Net/LAN</emphasis> + </para></entry> + </row> + </thead> + <tbody valign="middle"> + <row> + <entry><para> + Host-only + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry align="center"><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + – + </para></entry> + <entry><para> + – + </para></entry> + </row> + <row> + <entry><para> + Internal + </para></entry> + <entry><para> + – + </para></entry> + <entry><para> + – + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + – + </para></entry> + <entry><para> + – + </para></entry> + </row> + <row> + <entry><para> + Bridged + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + </row> + <row> + <entry><para> + NAT + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + <link linkend="natforward">Port forward</link> + </para></entry> + <entry><para> + – + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + <link linkend="natforward">Port forward</link> + </para></entry> + </row> + <row> + <entry><para> + NATservice + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + <link linkend="network_nat_service">Port forward</link> + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + <link linkend="network_nat_service">Port forward</link> + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + The following sections describe the available network modes in + more detail. + </para> + + </sect1> + + <sect1 id="network_nat"> + + <title>Network Address Translation (NAT)</title> + + <para> + Network Address Translation (NAT) is the simplest way of accessing + an external network from a virtual machine. Usually, it does not + require any configuration on the host network and guest system. + For this reason, it is the default networking mode in + &product-name;. + </para> + + <para> + A virtual machine with NAT enabled acts much like a real computer + that connects to the Internet through a router. The router, in + this case, is the &product-name; networking engine, which maps + traffic from and to the virtual machine transparently. In + &product-name; this router is placed between each virtual machine + and the host. This separation maximizes security since by default + virtual machines cannot talk to each other. + </para> + + <para> + The disadvantage of NAT mode is that, much like a private network + behind a router, the virtual machine is invisible and unreachable + from the outside internet. You cannot run a server this way unless + you set up port forwarding. See <xref linkend="natforward"/>. + </para> + + <para> + The network frames sent out by the guest operating system are + received by &product-name;'s NAT engine, which extracts the TCP/IP + data and resends it using the host operating system. To an + application on the host, or to another computer on the same + network as the host, it looks like the data was sent by the + &product-name; application on the host, using an IP address + belonging to the host. &product-name; listens for replies to the + packages sent, and repacks and resends them to the guest machine + on its private network. + </para> + + <note> + <para> + Even though the NAT engine separates the VM from the host, the + VM has access to the host's loopback interface and the network + services running on it. The host's loopback interface is + accessible as IP address 10.0.2.2. This access to the host's + loopback interface can be extremely useful in some cases, for + example when running a web application under development in the + VM and the database server on the loopback interface on the + host. + </para> + </note> + + <para> + The virtual machine receives its network address and configuration + on the private network from a DHCP server integrated into + &product-name;. The IP address thus assigned to the virtual + machine is usually on a completely different network than the + host. As more than one card of a virtual machine can be set up to + use NAT, the first card is connected to the private network + 10.0.2.0, the second card to the network 10.0.3.0 and so on. If + you need to change the guest-assigned IP range, see + <xref linkend="changenat" />. + </para> + + <sect2 id="natforward"> + + <title>Configuring Port Forwarding with NAT</title> + + <para> + As the virtual machine is connected to a private network + internal to &product-name; and invisible to the host, network + services on the guest are not accessible to the host machine or + to other computers on the same network. However, like a physical + router, &product-name; can make selected services available to + the world outside the guest through <emphasis>port + forwarding</emphasis>. This means that &product-name; listens to + certain ports on the host and resends all packets which arrive + there to the guest, on the same or a different port. + </para> + + <para> + To an application on the host or other physical or virtual + machines on the network, it looks as though the service being + proxied is actually running on the host. This also means that + you cannot run the same service on the same ports on the host. + However, you still gain the advantages of running the service in + a virtual machine. For example, services on the host machine or + on other virtual machines cannot be compromised or crashed by a + vulnerability or a bug in the service, and the service can run + in a different operating system than the host system. + </para> + + <para> + To configure port forwarding you can use the graphical + <emphasis role="bold">Port Forwarding</emphasis> editor which + can be found in the <emphasis role="bold">Network</emphasis> + settings dialog for network adaptors configured to use NAT. + Here, you can map host ports to guest ports to allow network + traffic to be routed to a specific port in the guest. + </para> + + <para> + Alternatively, the command line tool + <command>VBoxManage</command> can be used. See + <xref linkend="vboxmanage-modifyvm" />. + </para> + + <para> + You will need to know which ports on the guest the service uses + and to decide which ports to use on the host. You may want to + use the same ports on the guest and on the host. You can use any + ports on the host which are not already in use by a service. For + example, to set up incoming NAT connections to an + <command>ssh</command> server in the guest, use the following + command: + </para> + +<screen>VBoxManage modifyvm "VM name" --nat-pf1 "guestssh,tcp,,2222,,22"</screen> + + <para> + In the above example, all TCP traffic arriving on port 2222 on + any host interface will be forwarded to port 22 in the guest. + The protocol name <literal>tcp</literal> is a mandatory + attribute defining which protocol should be used for forwarding, + <literal>udp</literal> could also be used. The name + <literal>guestssh</literal> is purely descriptive and will be + auto-generated if omitted. The number after + <option>--nat-pf</option> denotes the network card, as with + other <command>VBoxManage</command> commands. + </para> + + <para> + To remove this forwarding rule, use the following command: + </para> + +<screen>VBoxManage modifyvm "VM name" --natpf1 delete "guestssh"</screen> + + <para> + If for some reason the guest uses a static assigned IP address + not leased from the built-in DHCP server, it is required to + specify the guest IP when registering the forwarding rule, as + follows: + </para> + +<screen>VBoxManage modifyvm "VM name" --natpf1 "guestssh,tcp,,2222,10.0.2.19,22"</screen> + + <para> + This example is identical to the previous one, except that the + NAT engine is being told that the guest can be found at the + 10.0.2.19 address. + </para> + + <para> + To forward <emphasis>all</emphasis> incoming traffic from a + specific host interface to the guest, specify the IP of that + host interface as follows: + </para> + +<screen>VBoxManage modifyvm "VM name" --natpf1 "guestssh,tcp,127.0.0.1,2222,,22"</screen> + + <para> + This example forwards all TCP traffic arriving on the localhost + interface at 127.0.0.1 through port 2222 to port 22 in the + guest. + </para> + + <para> + It is possible to configure incoming NAT connections while the + VM is running, see <xref linkend="vboxmanage-controlvm"/>. + </para> + + </sect2> + + <sect2 id="nat-tftp"> + + <title>PXE Booting with NAT</title> + + <para> + PXE booting is now supported in NAT mode. The NAT DHCP server + provides a boot file name of the form + <filename><replaceable>vmname</replaceable>.pxe</filename> if + the directory <literal>TFTP</literal> exists in the directory + where the user's <filename>VirtualBox.xml</filename> file is + kept. It is the responsibility of the user to provide + <filename><replaceable>vmname</replaceable>.pxe</filename>. + </para> + + </sect2> + + <sect2 id="nat-limitations"> + + <title>NAT Limitations</title> + + <para> + There are some limitations of NAT mode which users should be + aware of, as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">ICMP protocol limitations.</emphasis> + Some frequently used network debugging tools, such as + <command>ping</command> or <command>traceroute</command>, + rely on the ICMP protocol for sending and receiving + messages. &product-name; ICMP support has some limitations, + meaning <command>ping</command> should work but some other + tools may not work reliably. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Receiving of UDP + broadcasts.</emphasis> The guest does not reliably receive + UDP broadcasts. In order to save resources, it only listens + for a certain amount of time after the guest has sent UDP + data on a particular port. As a consequence, NetBios name + resolution based on broadcasts does not always work, but + WINS always works. As a workaround, you can use the numeric + IP of the desired server in the + <filename>\\<replaceable>server</replaceable>\<replaceable>share</replaceable></filename> + notation. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Some protocols are not + supported.</emphasis> Protocols other than TCP and UDP are + not supported. GRE is not supported. This means some VPN + products, such as PPTP from Microsoft, cannot be used. There + are other VPN products which use only TCP and UDP. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Forwarding host ports below + 1024.</emphasis> On UNIX-based hosts, such as Linux, Oracle + Solaris, and macOS, it is not possible to bind to ports + below 1024 from applications that are not run by + <literal>root</literal>. As a result, if you try to + configure such a port forwarding, the VM will refuse to + start. + </para> + </listitem> + + </itemizedlist> + + <para> + These limitations normally do not affect standard network use. + But the presence of NAT has also subtle effects that may + interfere with protocols that are normally working. One example + is NFS, where the server is often configured to refuse + connections from non-privileged ports, which are those ports not + below 1024. + </para> + + </sect2> + + </sect1> + + <sect1 id="network_nat_service"> + + <title>Network Address Translation Service</title> + + <para> + The Network Address Translation (NAT) service works in a similar + way to a home router, grouping the systems using it into a network + and preventing systems outside of this network from directly + accessing systems inside it, but letting systems inside + communicate with each other and with systems outside using TCP and + UDP over IPv4 and IPv6. + </para> + + <para> + A NAT service is attached to an internal network. Virtual machines + which are to make use of it should be attached to that internal + network. The name of internal network is chosen when the NAT + service is created and the internal network will be created if it + does not already exist. The following is an example command to + create a NAT network: + </para> + +<screen>VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable</screen> + + <para> + Here, natnet1 is the name of the internal network to be used and + 192.168.15.0/24 is the network address and mask of the NAT service + interface. By default in this static configuration the gateway + will be assigned the address 192.168.15.1, the address following + the interface address, though this is subject to change. To attach + a DHCP server to the internal network, modify the example command + as follows: + </para> + +<screen>VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable --dhcp on</screen> + + <para> + To add a DHCP server to an existing network, use the following + command: + </para> + +<screen>VBoxManage natnetwork modify --netname natnet1 --dhcp on</screen> + + <para> + To disable the DHCP server, use the following command: + </para> + +<screen>VBoxManage natnetwork modify --netname natnet1 --dhcp off</screen> + + <para> + A DHCP server provides a list of registered nameservers, but does + not map servers from the 127/8 network. + </para> + + <para> + To start the NAT service, use the following command: + </para> + +<screen>VBoxManage natnetwork start --netname natnet1</screen> + + <para> + If the network has a DHCP server attached then it will start + together with the NAT network service. + </para> + + <para> + To stop the NAT network service, together with any DHCP server: + </para> + +<screen>VBoxManage natnetwork stop --netname natnet1</screen> + + <para> + To delete the NAT network service: + </para> + +<screen>VBoxManage natnetwork remove --netname natnet1</screen> + + <para> + This command does not remove the DHCP server if one is enabled on + the internal network. + </para> + + <para> + Port-forwarding is supported, using the + <option>--port-forward-4</option> switch for IPv4 and + <option>--port-forward-6</option> for IPv6. For example: + </para> + +<screen>VBoxManage natnetwork modify \ + --netname natnet1 --port-forward-4 "ssh:tcp:[]:1022:[192.168.15.5]:22"</screen> + + <para> + This adds a port-forwarding rule from the host's TCP 1022 port to + the port 22 on the guest with IP address 192.168.15.5. Host port, + guest port and guest IP are mandatory. To delete the rule, use the + following command: + </para> + +<screen>VBoxManage natnetwork modify --netname natnet1 --port-forward-4 delete ssh</screen> + + <para> + It is possible to bind a NAT service to specified interface. For + example: + </para> + +<screen>VBoxManage setextradata global "NAT/win-nat-test-0/SourceIp4" 192.168.1.185</screen> + + <para> + To see the list of registered NAT networks, use the following + command: + </para> + +<screen>VBoxManage list natnetworks</screen> + + <para> + NAT networks can also be created, deleted, and configured using + the Network Manager tool in &vbox-mgr;. Click + <emphasis role="bold">File</emphasis>, <emphasis role="bold"> + Tools</emphasis>, <emphasis role="bold">Network + Manager</emphasis>. See <xref linkend="network-manager"/>. + </para> + + <note> + <para> + Even though the NAT service separates the VM from the host, the + VM has access to the host's loopback interface and the network + services running on it. The host's loopback interface is + accessible as IP address 10.0.2.2 (assuming the default + configuration, in other configurations it's the respective + address in the configured IPv4 or IPv6 network range). This + access to the host's loopback interface can be extremely useful + in some cases, for example when running a web application under + development in the VM and the database server on the loopback + interface on the host. + </para> + </note> + + </sect1> + + <sect1 id="network_bridged"> + + <title>Bridged Networking</title> + + <para> + With bridged networking, &product-name; uses a device driver on + your <emphasis>host</emphasis> system that filters data from your + physical network adapter. This driver is therefore called a + <emphasis>net filter</emphasis> driver. This enables + &product-name; to intercept data from the physical network and + inject data into it, effectively creating a new network interface + in software. When a guest is using such a new software interface, + it looks to the host system as though the guest were physically + connected to the interface using a network cable. The host can + send data to the guest through that interface and receive data + from it. This means that you can set up routing or bridging + between the guest and the rest of your network. + </para> + + <note> + <para> + Even though TAP interfaces are no longer necessary on Linux for + bridged networking, you <emphasis>can</emphasis> still use TAP + interfaces for certain advanced setups, since you can connect a + VM to any host interface. + </para> + </note> + + <para> + To enable bridged networking, open the + <emphasis role="bold">Settings</emphasis> dialog of a virtual + machine, go to the <emphasis role="bold">Network</emphasis> page + and select <emphasis role="bold">Bridged Network</emphasis> in the + drop-down list for the <emphasis role="bold">Attached + To</emphasis> field. Select a host interface from the list at the + bottom of the page, which contains the physical network interfaces + of your systems. On a typical MacBook, for example, this will + allow you to select between en1: AirPort, which is the wireless + interface, and en0: Ethernet, which represents the interface with + a network cable. + </para> + + <note> + <para> + Bridging to a wireless interface is done differently from + bridging to a wired interface, because most wireless adapters do + not support promiscuous mode. All traffic has to use the MAC + address of the host's wireless adapter, and therefore + &product-name; needs to replace the source MAC address in the + Ethernet header of an outgoing packet to make sure the reply + will be sent to the host interface. When &product-name; sees an + incoming packet with a destination IP address that belongs to + one of the virtual machine adapters it replaces the destination + MAC address in the Ethernet header with the VM adapter's MAC + address and passes it on. &product-name; examines ARP and DHCP + packets in order to learn the IP addresses of virtual machines. + </para> + </note> + + <para> + Depending on your host operating system, the following limitations + apply: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">macOS hosts.</emphasis> Functionality is + limited when using AirPort, the Mac's wireless networking + system, for bridged networking. Currently, &product-name; + supports only IPv4 and IPv6 over AirPort. For other protocols, + such as IPX, you must choose a wired interface. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Linux hosts.</emphasis> Functionality is + limited when using wireless interfaces for bridged networking. + Currently, &product-name; supports only IPv4 and IPv6 over + wireless. For other protocols, such as IPX, you must choose a + wired interface. + </para> + + <para> + Also, setting the MTU to less than 1500 bytes on wired + interfaces provided by the sky2 driver on the Marvell Yukon II + EC Ultra Ethernet NIC is known to cause packet losses under + certain conditions. + </para> + + <para> + Some adapters strip VLAN tags in hardware. This does not allow + you to use VLAN trunking between VM and the external network + with pre-2.6.27 Linux kernels, or with host operating systems + other than Linux. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Oracle Solaris hosts.</emphasis> There + is no support for using wireless interfaces. Filtering guest + traffic using IPFilter is also not completely supported due to + technical restrictions of the Oracle Solaris networking + subsystem. These issues may be addressed in later releases of + Oracle Solaris 11. + </para> + + <para> + On Oracle Solaris 11 hosts build 159 and above, it is possible + to use Oracle Solaris Crossbow Virtual Network Interfaces + (VNICs) directly with &product-name; without any additional + configuration other than each VNIC must be exclusive for every + guest network interface. + </para> + + <para> + When using VLAN interfaces with &product-name;, they must be + named according to the PPA-hack naming scheme, such as + e1000g513001. Otherwise, the guest may receive packets in an + unexpected format. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="network_internal"> + + <title>Internal Networking</title> + + <para> + Internal Networking is similar to bridged networking in that the + VM can directly communicate with the outside world. However, the + outside world is limited to other VMs on the same host which + connect to the same internal network. + </para> + + <para> + Even though technically, everything that can be done using + internal networking can also be done using bridged networking, + there are security advantages with internal networking. In bridged + networking mode, all traffic goes through a physical interface of + the host system. It is therefore possible to attach a packet + sniffer such as Wireshark to the host interface and log all + traffic that goes over it. If, for any reason, you prefer two or + more VMs on the same machine to communicate privately, hiding + their data from both the host system and the user, bridged + networking therefore is not an option. + </para> + + <para> + Internal networks are created automatically as needed. There is no + central configuration. Every internal network is identified simply + by its name. Once there is more than one active virtual network + card with the same internal network ID, the &product-name; support + driver will automatically <emphasis>wire</emphasis> the cards and + act as a network switch. The &product-name; support driver + implements a complete Ethernet switch and supports both + broadcast/multicast frames and promiscuous mode. + </para> + + <para> + In order to attach a VM's network card to an internal network, set + its networking mode to Internal Networking. There are two ways to + accomplish this: + </para> + + <itemizedlist> + + <listitem> + <para> + Use the VM's <emphasis role="bold">Settings</emphasis> window + in &vbox-mgr;. In the <emphasis role="bold">Network</emphasis> + category of the Settings window, select + <emphasis role="bold">Internal Network</emphasis> from the + drop-down list of networking modes. Select the name of an + existing internal network from the drop-down list below, or + enter a new name into the + <emphasis role="bold">Name</emphasis> field. + </para> + </listitem> + + <listitem> + <para> + Use the command line, for example: + </para> + +<screen>VBoxManage modifyvm "VM name" --nic<x> intnet</screen> + + <para> + Optionally, you can specify a network name with the command: + </para> + +<screen>VBoxManage modifyvm "VM name" --intnet<x> "network name"</screen> + + <para> + If you do not specify a network name, the network card will be + attached to the network <literal>intnet</literal> by default. + </para> + </listitem> + + </itemizedlist> + + <para> + Unless you configure the virtual network cards in the guest + operating systems that are participating in the internal network + to use static IP addresses, you may want to use the DHCP server + that is built into &product-name; to manage IP addresses for the + internal network. See <xref linkend="vboxmanage-dhcpserver" />. + </para> + + <para> + As a security measure, by default, the Linux implementation of + internal networking only allows VMs running under the same user ID + to establish an internal network. However, it is possible to + create a shared internal networking interface, accessible by users + with different user IDs. + </para> + + </sect1> + + <sect1 id="network_hostonly"> + + <title>Host-Only Networking</title> + + <para> + Host-only networking can be thought of as a hybrid between the + bridged and internal networking modes. As with bridged networking, + the virtual machines can talk to each other and the host as if + they were connected through a physical Ethernet switch. As with + internal networking, a physical networking interface need not be + present, and the virtual machines cannot talk to the world outside + the host since they are not connected to a physical networking + interface. + </para> + + <para> + When host-only networking is used, &product-name; creates a new + software interface on the host which then appears next to your + existing network interfaces. In other words, whereas with bridged + networking an existing physical interface is used to attach + virtual machines to, with host-only networking a new + <emphasis>loopback</emphasis> interface is created on the host. + And whereas with internal networking, the traffic between the + virtual machines cannot be seen, the traffic on the loopback + interface on the host can be intercepted. + </para> + + <note> + <para> + Hosts running recent macOS versions do not support host-only + adapters. These adapters are replaced by host-only networks, + which define a network mask and an IP address range, where the + host network interface receives the lowest address in the range. + </para> + + <para> + The host network interface gets added and removed dynamically by + the operating system, whenever a host-only network is used by + virtual machines. + </para> + + <para> + On macOS hosts, choose the <emphasis role="bold">Host-Only + Network</emphasis> option when configuring a network adapter. + The <emphasis role="bold">Host-Only Adapter</emphasis> option is + provided for legacy support. + </para> + </note> + + <para> + Host-only networking is particularly useful for preconfigured + virtual appliances, where multiple virtual machines are shipped + together and designed to cooperate. For example, one virtual + machine may contain a web server and a second one a database, and + since they are intended to talk to each other, the appliance can + instruct &product-name; to set up a host-only network for the two. + A second, bridged, network would then connect the web server to + the outside world to serve data to, but the outside world cannot + connect to the database. + </para> + + <para> + To enable a host-only network interface for a virtual machine, do + either of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Go to the <emphasis role="bold">Network</emphasis> page in the + virtual machine's <emphasis role="bold">Settings</emphasis> + dialog and select an <emphasis role="bold">Adapter</emphasis> + tab. Ensure that the <emphasis role="bold">Enable Network + Adapter</emphasis> check box is selected and choose + <emphasis role="bold">Host-Only Adapter</emphasis> for the + <emphasis role="bold">Attached To</emphasis> field. + </para> + </listitem> + + <listitem> + <para> + On the command line, use <command>VBoxManage modifyvm + <replaceable>vmname</replaceable> + --nic<replaceable>x</replaceable> hostonly</command>. See + <xref linkend="vboxmanage-modifyvm" />. + </para> + </listitem> + + </itemizedlist> + + <para> + For host-only networking, as with internal networking, you may + find the DHCP server useful that is built into &product-name;. + This is enabled by default and manages the IP addresses in the + host-only network. Without the DHCP server you would need to + configure all IP addresses statically. + </para> + + <itemizedlist> + + <listitem> + <para> + In &vbox-mgr; you can configure the DHCP server by choosing + <emphasis role="bold">File</emphasis>, + <emphasis role="bold">Tools</emphasis>, + <emphasis role="bold">Network Manager</emphasis>. The Network + Manager window lists all host-only networks which are + presently in use. Select the network name and then use the + <emphasis role="bold">DHCP Server</emphasis> tab to configure + DHCP server settings. See <xref linkend="network-manager"/>. + </para> + </listitem> + + <listitem> + <para> + Alternatively, you can use the <command>VBoxManage + dhcpserver</command> command. See + <xref linkend="vboxmanage-dhcpserver" />. + </para> + </listitem> + + </itemizedlist> + + <note> + <para> + On Linux and macOS hosts the number of host-only interfaces is + limited to 128. There is no such limit for Oracle Solaris and + Windows hosts. + </para> + </note> + + <para> + On Linux, macOS and Solaris &product-name; will only allow IP + addresses in 192.168.56.0/21 range to be assigned to host-only + adapters. For IPv6 only link-local addresses are allowed. If other + ranges are desired, they can be enabled by creating + <filename>/etc/vbox/networks.conf</filename> and specifying + allowed ranges there. For example, to allow 10.0.0.0/8 and + 192.168.0.0/16 IPv4 ranges as well as 2001::/64 range put the + following lines into <filename>/etc/vbox/networks.conf</filename>: + </para> + +<screen> + * 10.0.0.0/8 192.168.0.0/16 + * 2001::/64 + </screen> + + <para> + Lines starting with the hash <command>#</command> are ignored. The + following example allows any addresses, effectively disabling + range control: + </para> + +<screen> + * 0.0.0.0/0 ::/0 + </screen> + + <para> + If the file exists, but no ranges are specified in it, no + addresses will be assigned to host-only adapters. The following + example effectively disables all ranges: + </para> + +<screen> + # No addresses are allowed for host-only adapters + </screen> + + </sect1> + + <sect1 id="network_udp_tunnel"> + + <title>UDP Tunnel Networking</title> + + <para> + This networking mode enables you to interconnect virtual machines + running on different hosts. + </para> + + <para> + Technically this is done by encapsulating Ethernet frames sent or + received by the guest network card into UDP/IP datagrams, and + sending them over any network available to the host. + </para> + + <para> + UDP Tunnel mode has the following parameters: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Source UDP port:</emphasis> The port on + which the host listens. Datagrams arriving on this port from + any source address will be forwarded to the receiving part of + the guest network card. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Destination address:</emphasis> IP + address of the target host of the transmitted data. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Destination UDP port:</emphasis> Port + number to which the transmitted data is sent. + </para> + </listitem> + + </itemizedlist> + + <para> + When interconnecting two virtual machines on two different hosts, + their IP addresses must be swapped. On a single host, source and + destination UDP ports must be swapped. + </para> + + <para> + In the following example, host 1 uses the IP address 10.0.0.1 and + host 2 uses IP address 10.0.0.2. To configure using the + command-line: + </para> + +<screen> VBoxManage modifyvm "VM 01 on host 1" --nic<x> generic + VBoxManage modifyvm "VM 01 on host 1" --nic-generic-drv<x> UDPTunnel + VBoxManage modifyvm "VM 01 on host 1" --nic-property<x> dest=10.0.0.2 + VBoxManage modifyvm "VM 01 on host 1" --nic-property<x> sport=10001 + VBoxManage modifyvm "VM 01 on host 1" --nic-property<x> dport=10002</screen> + +<screen> VBoxManage modifyvm "VM 02 on host 2" --nic<y> generic + VBoxManage modifyvm "VM 02 on host 2" --nic-generic-drv<y> UDPTunnel + VBoxManage modifyvm "VM 02 on host 2" --nic-property<y> dest=10.0.0.1 + VBoxManage modifyvm "VM 02 on host 2" --nic-property<y> sport=10002 + VBoxManage modifyvm "VM 02 on host 2" --nic-property<y> dport=10001</screen> + + <para> + Of course, you can always interconnect two virtual machines on the + same host, by setting the destination address parameter to + 127.0.0.1 on both. It will act similarly to an internal network in + this case. However, the host can see the network traffic which it + could not in the normal internal network case. + </para> + + <note> + <para> + On UNIX-based hosts, such as Linux, Oracle Solaris, and Mac OS + X, it is not possible to bind to ports below 1024 from + applications that are not run by <literal>root</literal>. As a + result, if you try to configure such a source UDP port, the VM + will refuse to start. + </para> + </note> + + </sect1> + + <sect1 id="network_vde"> + + <title>VDE Networking</title> + + <para> + Virtual Distributed Ethernet (VDE) is a flexible, virtual network + infrastructure system, spanning across multiple hosts in a secure + way. It enables L2/L3 switching, including spanning-tree protocol, + VLANs, and WAN emulation. It is an optional part of &product-name; + which is only included in the source code. + </para> + + <para> + VDE is a project developed by Renzo Davoli, Associate Professor at + the University of Bologna, Italy. + </para> + + <para> + The basic building blocks of the infrastructure are VDE switches, + VDE plugs, and VDE wires which interconnect the switches. + </para> + + <para> + The &product-name; VDE driver has a single parameter: VDE network. + This is the name of the VDE network switch socket to which the VM + will be connected. + </para> + + <para> + The following basic example shows how to connect a virtual machine + to a VDE switch. + </para> + + <orderedlist> + + <listitem> + <para> + Create a VDE switch: + </para> + +<screen>vde_switch -s /tmp/switch1</screen> + </listitem> + + <listitem> + <para> + Configure VMs using the command-line: + </para> + +<screen>VBoxManage modifyvm "VM name" --nic<x> generic</screen> + +<screen>VBoxManage modifyvm "VM name" --nic-generic-drv<x> VDE</screen> + + <para> + To connect to an automatically allocated switch port: + </para> + +<screen>VBoxManage modifyvm "VM name" --nic-property<x> network=/tmp/switch1</screen> + + <para> + To connect to a specific switch port + <replaceable>n</replaceable>: + </para> + +<screen>VBoxManage modifyvm "VM name" --nic-property<x> network=/tmp/switch1[<n>]</screen> + + <para> + This command can be useful for VLANs. + </para> + </listitem> + + <listitem> + <para> + (Optional) Map between a VDE switch port and a VLAN. + </para> + + <para> + Using the switch command line: + </para> + +<screen>vde$ vlan/create <VLAN></screen> + +<screen>vde$ port/setvlan <port> <VLAN></screen> + </listitem> + + </orderedlist> + + <para> + VDE is available on Linux and FreeBSD hosts only. It is only + available if the VDE software and the VDE plugin library from the + VirtualSquare project are installed on the host system. + </para> + + <note> + <para> + For Linux hosts, the shared library libvdeplug.so must be + available in the search path for shared libraries. + </para> + </note> + + <para> + For more information on setting up VDE networks, please see the + documentation accompanying the software. See also + <ulink url="http://wiki.virtualsquare.org" />. + </para> + + </sect1> + + <sect1 id="network_cloud"> + + <title>Cloud Networks</title> + + <para> + Cloud networks can be used for connections from a local VM to a + subnet on a remote &oci; instance. See + <xref linkend="network-manager-cloud-network-tab"/> for details of + how to create and configure a cloud network using the Network + Manager tool in &vbox-mgr;. + </para> + + <para> + To enable a cloud network interface for a virtual machine, do + either of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Go to the <emphasis role="bold">Network</emphasis> page in the + virtual machine's <emphasis role="bold">Settings</emphasis> + dialog and select an <emphasis role="bold">Adapter</emphasis> + tab. Ensure that the <emphasis role="bold">Enable Network + Adapter</emphasis> check box is selected and choose + <emphasis role="bold">Cloud Network</emphasis> for the + <emphasis role="bold">Attached To</emphasis> field. + </para> + </listitem> + + <listitem> + <para> + On the command line, use <command>VBoxManage modifyvm + <replaceable>vmname</replaceable> + --nic<replaceable>x</replaceable> cloud</command>. See + <xref linkend="vboxmanage-modifyvm" />. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="network-manager"> + + <title>Network Manager</title> + + <para> + The <emphasis role="bold">Network Manager</emphasis> tool in + &vbox-mgr; enables you to create, delete, and configure the + following types of networks used by &product-name;: + </para> + + <itemizedlist> + + <listitem> + <para> + Host-only networks. See + <xref linkend="network-manager-host-only-tab"/>. + </para> + </listitem> + + <listitem> + <para> + NAT networks. See + <xref linkend="network-manager-nat-network-tab"/>. + </para> + </listitem> + + <listitem> + <para> + Cloud networks. See + <xref linkend="network-manager-cloud-network-tab"/>. + </para> + </listitem> + + </itemizedlist> + + <para> + To display the Network Manager, go to the global + <emphasis role="bold">Tools</emphasis> menu and click + <emphasis role="bold">Network</emphasis>. + </para> + + <sect2 id="network-manager-host-only-tab"> + + <title>Host-Only Networks Tab</title> + + <para> + The Host-Only Networks tab in Network Manager lists all + host-only networks that are currently in use. + </para> + + <itemizedlist> + + <listitem> + <para> + Click <emphasis role="bold">Create</emphasis> to add a new + host-only network to the list. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Remove</emphasis> to remove a + host-only network from the list. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Properties</emphasis> to show or + hide settings for the selected host-only network. + </para> + </listitem> + + </itemizedlist> + + <para> + To configure a host-only network, select the network name in the + <emphasis role="bold">Name</emphasis> field and do the + following: + </para> + + <itemizedlist> + + <listitem> + <para> + Use the <emphasis role="bold">Adapter</emphasis> tab to + configure the network adapter for the host-only network. + </para> + </listitem> + + <listitem> + <para> + Use the <emphasis role="bold">DHCP Server</emphasis> tab to + configure settings for the DHCP server used by the host-only + network. The DHCP server is built into &product-name; and + manages IP addresses for the network automatically. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="network-manager-nat-network-tab"> + + <title>NAT Networks Tab</title> + + <para> + The NAT Networks tab in Network Manager lists all NAT networks + that are currently in use. + </para> + + <itemizedlist> + + <listitem> + <para> + Click <emphasis role="bold">Create</emphasis> to add a new + NAT network to the list. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Remove</emphasis> to remove a + NAT network from the list. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Properties</emphasis> to show or + hide settings for the selected NAT network. + </para> + </listitem> + + </itemizedlist> + + <para> + To configure a NAT network, select the network name in the + <emphasis role="bold">Name</emphasis> field and do the + following: + </para> + + <itemizedlist> + + <listitem> + <para> + Use the <emphasis role="bold">General Options</emphasis> tab + to configure the network settings used by the NAT network. + For example, the network address and mask of the NAT service + interface. + </para> + </listitem> + + <listitem> + <para> + Use the <emphasis role="bold">Port Forwarding</emphasis> tab + to configure port forwarding rules used by the NAT network. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="network-manager-cloud-network-tab"> + + <title>Cloud Networks Tab</title> + + <para> + The Cloud Networks tab in Network Manager lists all cloud + networks that are currently in use. + </para> + + <itemizedlist> + + <listitem> + <para> + Click <emphasis role="bold">Create</emphasis> to add a new + cloud network to the list. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Remove</emphasis> to remove a + cloud network from the list. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Properties</emphasis> to show or + hide settings for the selected cloud network. + </para> + </listitem> + + </itemizedlist> + + <para> + To configure a cloud network, select the network name in the + <emphasis role="bold">Name</emphasis> field and specify the + following: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Name:</emphasis> The name used for the + cloud network. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Provider:</emphasis> The cloud service + provider, such as &oci;. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Profile:</emphasis> The cloud profile + used to connect to the cloud network. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">ID:</emphasis> The OCID for the cloud + tunneling network. Click the + <emphasis role="bold">Network</emphasis> icon to view the + subnets on &oci; that are available for tunneling traffic. + </para> + + <para> + See <xref linkend="cloud-using-cloud-networks"/> for details + of how you can use the <command>VBoxManage cloud</command> + command to create and configure a virtual cloud network + (VCN) on &oci;. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + </sect1> + + <sect1 id="network_bandwidth_limit"> + + <title>Limiting Bandwidth for Network Input/Output</title> + + <para> + &product-name; supports limiting of the maximum bandwidth used for + network transmission. Several network adapters of one VM may share + limits through bandwidth groups. It is possible to have more than + one such limit. + </para> + + <note> + <para> + &product-name; shapes VM traffic only in the transmit direction, + delaying the packets being sent by virtual machines. It does not + limit the traffic being received by virtual machines. + </para> + </note> + + <para> + Limits are configured through <command>VBoxManage</command>. The + following example creates a bandwidth group named Limit, sets the + limit to 20 Mbps and assigns the group to the first and second + adapters of the VM: + </para> + +<screen>VBoxManage bandwidthctl "VM name" add Limit --type network --limit 20m +VBoxManage modifyvm "VM name" --nicbandwidthgroup1 Limit +VBoxManage modifyvm "VM name" --nicbandwidthgroup2 Limit</screen> + + <para> + All adapters in a group share the bandwidth limit, meaning that in + the example above the bandwidth of both adapters combined can + never exceed 20 Mbps. However, if one adapter does not require + bandwidth the other can use the remaining bandwidth of its group. + </para> + + <para> + The limits for each group can be changed while the VM is running, + with changes being picked up immediately. The following example + changes the limit for the group created in the previous example to + 100 Kbps: + </para> + +<screen>VBoxManage bandwidthctl "VM name" set Limit --limit 100k</screen> + + <para> + To completely disable shaping for the first adapter of VM use the + following command: + </para> + +<screen>VBoxManage modifyvm "VM name" --nicbandwidthgroup1 none</screen> + + <para> + It is also possible to disable shaping for all adapters assigned + to a bandwidth group while VM is running, by specifying the zero + limit for the group. For example, for the bandwidth group named + Limit: + </para> + +<screen>VBoxManage bandwidthctl "VM name" set Limit --limit 0</screen> + + </sect1> + + <sect1 id="network_performance"> + + <title>Improving Network Performance</title> + + <para> + &product-name; provides a variety of virtual network adapters that + can be attached to the host's network in a number of ways. + Depending on which types of adapters and attachments are used the + network performance will be different. Performance-wise the virtio + network adapter is preferable over Intel PRO/1000 emulated + adapters, which are preferred over the PCNet family of adapters. + Both virtio and Intel PRO/1000 adapters enjoy the benefit of + segmentation and checksum offloading. Segmentation offloading is + essential for high performance as it allows for less context + switches, dramatically increasing the sizes of packets that cross + the VM/host boundary. + </para> + + <note> + <para> + Neither virtio nor Intel PRO/1000 drivers for Windows XP support + segmentation offloading. Therefore Windows XP guests never reach + the same transmission rates as other guest types. Refer to MS + Knowledge base article 842264 for additional information. + </para> + </note> + + <para> + Three attachment types: Internal, Bridged, and Host-Only, have + nearly identical performance. The Internal type is a little bit + faster and uses less CPU cycles as the packets never reach the + host's network stack. The NAT attachment type is the slowest and + most secure of all attachment types, as it provides network + address translation. The generic driver attachment is special and + cannot be considered as an alternative to other attachment types. + </para> + + <para> + The number of CPUs assigned to VM does not improve network + performance and in some cases may hurt it due to increased + concurrency in the guest. + </para> + + <para> + Here is a short summary of things to check in order to improve + network performance: + </para> + + <itemizedlist> + + <listitem> + <para> + Whenever possible use the virtio network adapter. Otherwise, + use one of the Intel PRO/1000 adapters. + </para> + </listitem> + + <listitem> + <para> + Use a Bridged attachment instead of NAT. + </para> + </listitem> + + <listitem> + <para> + Make sure segmentation offloading is enabled in the guest OS. + Usually it will be enabled by default. You can check and + modify offloading settings using the + <command>ethtool</command> command on Linux guests. + </para> + </listitem> + + <listitem> + <para> + Perform a full detailed analysis of network traffic on the + VM's network adaptor using a third party tool such as + Wireshark. To do this, a promiscuous mode policy needs to be + used on the VM's network adaptor. Use of this mode is only + possible on the following network types: NAT Network, Bridged + Adapter, Internal Network, and Host-Only Adapter. + </para> + + <para> + To setup a promiscuous mode policy, either select from the + drop down list located in the <emphasis role="bold">Network + Settings</emphasis> dialog for the network adaptor or use the + command line tool <command>VBoxManage</command>. See + <xref linkend="vboxmanage-modifyvm" />. + </para> + + <para> + Promiscuous mode policies are as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <literal>deny</literal>, which hides any traffic not + intended for the VM's network adaptor. This is the default + setting. + </para> + </listitem> + + <listitem> + <para> + <literal>allow-vms</literal>, which hides all host traffic + from the VM's network adaptor, but allows it to see + traffic from and to other VMs. + </para> + </listitem> + + <listitem> + <para> + <literal>allow-all</literal>, which removes all + restrictions. The VM's network adaptor sees all traffic. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + + </sect1> + +</chapter> diff --git a/doc/manual/en_US/user_Preface.xml b/doc/manual/en_US/user_Preface.xml new file mode 100644 index 00000000..41831d03 --- /dev/null +++ b/doc/manual/en_US/user_Preface.xml @@ -0,0 +1,114 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" +[ + <!ENTITY % all.entities SYSTEM "all-entities.ent"> + %all.entities; +]> +<preface id="user-preface"> + + <title>Preface</title> + + <para> + The <citetitle>&product-name; User Manual</citetitle> provides an + introduction to using &product-name;. The manual provides + information on how to install &product-name; and use it to create + and configure virtual machines. + </para> + + <simplesect id="user-preface-audience"> + + <title>Audience</title> + + <para> + This document is intended for both new and existing users of + &product-name;. It is assumed that readers are familiar with Web + technologies and have a general understanding of Windows and UNIX + platforms. + </para> + + </simplesect> + + <simplesect id="user-preface-reldocs"> + + <title>Related Documents</title> + + <para> + The documentation for this product is available at: + </para> + + <para> + <ulink url="&ohc-doc-page;" /> + </para> + + </simplesect> + + <simplesect id="user-preface-convs"> + + <title>Conventions</title> + + <para> + The following text conventions are used in this document: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">boldface</emphasis>: Boldface type + indicates graphical user interface elements associated with an + action, or terms defined in text or the glossary. + </para> + </listitem> + + <listitem> + <para> + <emphasis>italic</emphasis>: Italic type indicates book + titles, emphasis, or placeholder variables for which you + supply particular values. + </para> + </listitem> + + <listitem> + <para> + <literal>monospace</literal>: Monospace type indicates + commands within a paragraph, URLs, code in examples, text that + appears on the screen, or text that you enter. + </para> + </listitem> + + </itemizedlist> + + </simplesect> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="../common/oracle-accessibility-ohc-en.xml" /> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="../common/oracle-legal-notices/oracle-support-en.xml" /> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="../common/oracle-legal-notices/oracle-diversity.xml" /> + +</preface> diff --git a/doc/manual/en_US/user_PrivacyPolicy.xml b/doc/manual/en_US/user_PrivacyPolicy.xml new file mode 100644 index 00000000..f08c4369 --- /dev/null +++ b/doc/manual/en_US/user_PrivacyPolicy.xml @@ -0,0 +1,114 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<appendix id="privacy"> + + <title>&product-name; Privacy Information</title> + + <para> + Version 5, Dec 13, 2012 + </para> + + <para> + The Oracle Privacy Policies posted on + <ulink url="https://www.oracle.com/legal/privacy/privacy-policy.html" /> + apply to your personal data collected and used by Oracle. The + following privacy information describes in more detail which + information is exchanged between the &product-name; application and + Oracle, and which information is collected by the virtualbox.org + website. + </para> + + <para> + <emphasis role="bold">§ 1 virtualbox.org.</emphasis> The + "virtualbox.org" website logs anonymous usage information such as + your IP address, geographical location, browser type, referral + source, length of visit and number of page views while you visit + (collectively, "anonymous data"). In addition, but only if you + choose to register, the website's bug tracking and forum services + store the data you choose to reveal upon registration, such as your + user name and contact information. + </para> + + <para> + <emphasis role="bold">§ 2 Cookies.</emphasis> The virtualbox.org + website, the bug tracker and the forum services use cookies to + identify and track the visiting web browser and, if you have + registered, to facilitate login. Most browsers allow you to refuse + to accept cookies. While you can still visit the website with + cookies disabled, logging into the bug tracker and forum services + will most likely not work without them. + </para> + + <para> + <emphasis role="bold">§ 3 &product-name; registration + process.</emphasis> The &product-name; application may ask that the + user optionally register with Oracle. If you choose to register, + your name, e-mail address, country and company will be submitted to + Oracle and stored together with the IP address of the submitter as + well as product version and platform being used. + </para> + + <para> + <emphasis role="bold">§ 4 Update notifications.</emphasis> The + &product-name; application may contact Oracle to find out whether a + new version of &product-name; has been released and notify the user + if that is the case. In the process, anonymous data such as your IP + address and a non-identifying counter, together with the product + version and the platform being used, is sent so that the server can + find out whether an update is available. By default, this check is + performed once a day. You change this interval or disable these + checks altogether in the &product-name; preferences. + </para> + + <para> + <emphasis role="bold">§ 5 Usage of personal information.</emphasis> + Oracle may use anonymous and personal data collected by the means + above for statistical purposes as well as to automatically inform + you about new notices related to your posts on the bug tracker and + forum services, to administer the website and to contact you due to + technical issues. Oracle may also inform you about new product + releases related to &product-name;. + </para> + + <para> + In no event will personal data without your express consent be + provided to any third parties, unless Oracle may be required to do + so by law or in connection with legal proceedings. + </para> + + <para> + <emphasis role="bold">§ 6 Updates.</emphasis> Oracle may update the + privacy policy at any time by posting a new version at + <ulink url="https://www.oracle.com/legal/privacy/privacy-policy.html" /> + and the privacy information will be kept up to date in the + documentation which comes with the &product-name; application. You + should check these places occasionally to ensure you are happy with + any changes. + </para> + +</appendix> diff --git a/doc/manual/en_US/user_Security.xml b/doc/manual/en_US/user_Security.xml new file mode 100644 index 00000000..6c3b986e --- /dev/null +++ b/doc/manual/en_US/user_Security.xml @@ -0,0 +1,755 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="Security"> + + <title>Security Guide</title> + + <sect1 id="security-general"> + + <title>General Security Principles</title> + + <para> + The following principles are fundamental to using any application + securely. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Keep software up to date</emphasis>. One + of the principles of good security practise is to keep all + software versions and patches up to date. Activate the + &product-name; update notification to get notified when a new + &product-name; release is available. When updating + &product-name;, do not forget to update the Guest Additions. + Keep the host operating system as well as the guest operating + system up to date. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Restrict network access to critical + services.</emphasis> Use proper means, for instance a + firewall, to protect your computer and your guests from + accesses from the outside. Choosing the proper networking mode + for VMs helps to separate host networking from the guest and + vice versa. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Follow the principle of least + privilege.</emphasis> The principle of least privilege states + that users should be given the least amount of privilege + necessary to perform their jobs. Always execute &product-name; + as a regular user. We strongly discourage anyone from + executing &product-name; with system privileges. + </para> + + <para> + Choose restrictive permissions when creating configuration + files, for instance when creating /etc/default/virtualbox, see + <xref linkend="linux_install_opts"/>. Mode 0600 is preferred. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Monitor system activity.</emphasis> + System security builds on three pillars: good security + protocols, proper system configuration and system monitoring. + Auditing and reviewing audit records address the third + requirement. Each component within a system has some degree of + monitoring capability. Follow audit advice in this document + and regularly monitor audit records. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Keep up to date on latest security + information.</emphasis> Oracle continually improves its + software and documentation. Check this note yearly for + revisions. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="security-secure-install"> + + <title>Secure Installation and Configuration</title> + + <sect2 id="security-secure-install-overview"> + + <title>Installation Overview</title> + + <para> + The &product-name; base package should be downloaded only from a + trusted source, for instance the official website + <ulink url="http://www.virtualbox.org" />. The integrity of the + package should be verified with the provided SHA256 checksum + which can be found on the official website. + </para> + + <para> + General &product-name; installation instructions for the + supported hosts can be found in <xref linkend="installation"/>. + </para> + + <para> + On Windows hosts, the installer can be used to disable USB + support, support for bridged networking, support for host-only + networking and the Python language binding. See + <xref linkend="installation_windows"/>. All these features are + enabled by default but disabling some of them could be + appropriate if the corresponding functionality is not required + by any virtual machine. The Python language bindings are only + required if the &product-name; API is to be used by external + Python applications. In particular USB support and support for + the two networking modes require the installation of Windows + kernel drivers on the host. Therefore disabling those selected + features can not only be used to restrict the user to certain + functionality but also to minimize the surface provided to a + potential attacker. + </para> + + <para> + The general case is to install the complete &product-name; + package. The installation must be done with system privileges. + All &product-name; binaries should be executed as a regular user + and never as a privileged user. + </para> + + <para> + The &product-name; Extension Pack provides additional features + and must be downloaded and installed separately, see + <xref linkend="intro-installing"/>. As for the base package, the + SHA256 checksum of the extension pack should be verified. As the + installation requires system privileges, &product-name; will ask + for the system password during the installation of the extension + pack. + </para> + + </sect2> + + <sect2 id="security-secure-install-postinstall"> + + <title>Post Installation Configuration</title> + + <para> + Normally there is no post installation configuration of + &product-name; components required. However, on Oracle Solaris + and Linux hosts it is necessary to configure the proper + permissions for users executing VMs and who should be able to + access certain host resources. For instance, Linux users must be + member of the <emphasis>vboxusers</emphasis> group to be able to + pass USB devices to a guest. If a serial host interface should + be accessed from a VM, the proper permissions must be granted to + the user to be able to access that device. The same applies to + other resources like raw partitions, DVD/CD drives, and sound + devices. + </para> + + </sect2> + + </sect1> + + <sect1 id="security-features"> + + <title>Security Features</title> + + <para> + This section outlines the specific security mechanisms offered by + &product-name;. + </para> + + <sect2 id="security-model"> + + <title>The Security Model</title> + + <para> + One property of virtual machine monitors (VMMs) like + &product-name; is to encapsulate a guest by executing it in a + protected environment, a virtual machine, running as a user + process on the host operating system. The guest cannot + communicate directly with the hardware or other computers but + only through the VMM. The VMM provides emulated physical + resources and devices to the guest which are accessed by the + guest operating system to perform the required tasks. The VM + settings control the resources provided to the guest, for + example the amount of guest memory or the number of guest + processors and the enabled features for that guest. For example + remote control, certain screen settings and others. See + <xref linkend="generalsettings"/>. + </para> + + </sect2> + + <sect2 id="secure-config-vms"> + + <title>Secure Configuration of Virtual Machines</title> + + <para> + Several aspects of a virtual machine configuration are subject + to security considerations. + </para> + + <sect3 id="security-networking"> + + <title>Networking</title> + + <para> + The default networking mode for VMs is NAT which means that + the VM acts like a computer behind a router, see + <xref linkend="network_nat"/>. The guest is part of a private + subnet belonging to this VM and the guest IP is not visible + from the outside. This networking mode works without any + additional setup and is sufficient for many purposes. Keep in + mind that NAT allows access to the host operating system's + loopback interface. + </para> + + <para> + If bridged networking is used, the VM acts like a computer + inside the same network as the host, see + <xref linkend="network_bridged"/>. In this case, the guest has + the same network access as the host and a firewall might be + necessary to protect other computers on the subnet from a + potential malicious guest as well as to protect the guest from + a direct access from other computers. In some cases it is + worth considering using a forwarding rule for a specific port + in NAT mode instead of using bridged networking. + </para> + + <para> + Some setups do not require a VM to be connected to the public + network at all. Internal networking, see + <xref linkend="network_internal"/>, or host-only networking, + see <xref linkend="network_hostonly"/>, are often sufficient + to connect VMs among each other or to connect VMs only with + the host but not with the public network. + </para> + + </sect3> + + <sect3 id="security-vrdp-auth"> + + <title>VRDP Remote Desktop Authentication</title> + + <para> + When using the &product-name; Extension Pack provided by + Oracle for VRDP remote desktop support, you can optionally use + various methods to configure RDP authentication. The "null" + method is very insecure and should be avoided in a public + network. See <xref linkend="vbox-auth" />. + </para> + + </sect3> + + <sect3 id="security_clipboard"> + + <title>Clipboard</title> + + <para> + The shared clipboard enables users to share data between the + host and the guest. Enabling the clipboard in Bidirectional + mode enables the guest to read and write the host clipboard. + The Host to Guest mode and the Guest to Host mode limit the + access to one direction. If the guest is able to access the + host clipboard it can also potentially access sensitive data + from the host which is shared over the clipboard. + </para> + + <para> + If the guest is able to read from and/or write to the host + clipboard then a remote user connecting to the guest over the + network will also gain this ability, which may not be + desirable. As a consequence, the shared clipboard is disabled + for new machines. + </para> + + </sect3> + + <sect3 id="security-shared-folders"> + + <title>Shared Folders</title> + + <para> + If any host folder is shared with the guest then a remote user + connected to the guest over the network can access these files + too as the folder sharing mechanism cannot be selectively + disabled for remote users. + </para> + + </sect3> + + <sect3 id="security-3d-graphics"> + + <title>3D Graphics Acceleration</title> + + <para> + Enabling 3D graphics using the Guest Additions exposes the + host to additional security risks. See + <xref + linkend="guestadd-3d" />. + </para> + + </sect3> + + <sect3 id="security-cd-dvd-passthrough"> + + <title>CD/DVD Passthrough</title> + + <para> + Enabling CD/DVD passthrough enables the guest to perform + advanced operations on the CD/DVD drive, see + <xref linkend="storage-cds"/>. This could induce a security + risk as a guest could overwrite data on a CD/DVD medium. + </para> + + </sect3> + + <sect3 id="security-usb-passthrough"> + + <title>USB Passthrough</title> + + <para> + Passing USB devices to the guest provides the guest full + access to these devices, see <xref linkend="settings-usb"/>. + For instance, in addition to reading and writing the content + of the partitions of an external USB disk the guest will be + also able to read and write the partition table and hardware + data of that disk. + </para> + + </sect3> + + </sect2> + + <sect2 id="auth-config-using"> + + <title>Configuring and Using Authentication</title> + + <para> + The following components of &product-name; can use passwords for + authentication: + </para> + + <itemizedlist> + + <listitem> + <para> + When using remote iSCSI storage and the storage server + requires authentication, an initiator secret can optionally + be supplied with the <command>VBoxManage + storageattach</command> command. As long as no settings + password is provided, by using the command line option + <option>--settingspwfile</option>, then this secret is + stored <emphasis>unencrypted</emphasis> in the machine + configuration and is therefore potentially readable on the + host. See <xref linkend="storage-iscsi" /> and + <xref linkend="vboxmanage-storageattach" />. + </para> + </listitem> + + <listitem> + <para> + When using the &product-name; web service to control an + &product-name; host remotely, connections to the web service + are authenticated in various ways. This is described in + detail in the &product-name; Software Development Kit (SDK) + reference. See <xref linkend="VirtualBoxAPI" />. + </para> + </listitem> + + </itemizedlist> + + </sect2> + +<!-- + <sect2 id="access-control-config-using"> + <title>Configuring and Using Access Control</title> + </sect2> + + <sect2 id="security-audit-config-using"> + <title>Configuring and Using Security Audit</title> + </sect2> + + <sect2 id="security-other-features-config-using"> + <title>Configuring and Using Other Security Features</title> + </sect2> + --> + + <sect2 id="pot-insecure"> + + <title>Potentially Insecure Operations</title> + + <para> + The following features of &product-name; can present security + problems: + </para> + + <itemizedlist> + + <listitem> + <para> + Enabling 3D graphics using the Guest Additions exposes the + host to additional security risks. See + <xref + linkend="guestadd-3d" />. + </para> + </listitem> + + <listitem> + <para> + When teleporting a machine, the data stream through which + the machine's memory contents are transferred from one host + to another is not encrypted. A third party with access to + the network through which the data is transferred could + therefore intercept that data. An SSH tunnel could be used + to secure the connection between the two hosts. But when + considering teleporting a VM over an untrusted network the + first question to answer is how both VMs can securely access + the same virtual disk image with a reasonable performance. + </para><para> + If the network is not sufficiently trusted, the password + should be changed for each teleportation as the a 3rd party + could snoop up the unecrypted password hash when it is + transferred between the target and source host machines. + </para> + </listitem> + + <listitem> + <para> + When Page Fusion, see <xref linkend="guestadd-pagefusion"/>, + is enabled, it is possible that a side-channel opens up that + enables a malicious guest to determine the address space of + another VM running on the same host layout. For example, + where DLLs are typically loaded. This information leak in + itself is harmless, however the malicious guest may use it + to optimize attack against that VM through unrelated attack + vectors. It is recommended to only enable Page Fusion if you + do not think this is a concern in your setup. + </para> + </listitem> + + <listitem> + <para> + When using the &product-name; web service to control an + &product-name; host remotely, connections to the web + service, over which the API calls are transferred using SOAP + XML, are not encrypted. They use plain HTTP by default. This + is a potential security risk. For details about the web + service, see <xref linkend="VirtualBoxAPI" />. + </para> + + <para> + The web services are not started by default. See + <xref linkend="vboxwebsrv-daemon"/> to find out how to start + this service and how to enable SSL/TLS support. It has to be + started as a regular user and only the VMs of that user can + be controlled. By default, the service binds to localhost + preventing any remote connection. + </para> + </listitem> + + <listitem> + <para> + Traffic sent over a UDP Tunnel network attachment is not + encrypted. You can either encrypt it on the host network + level, with IPsec, or use encrypted protocols in the guest + network, such as SSH. The security properties are similar to + bridged Ethernet. + </para> + </listitem> + + <listitem> + <para> + Because of shortcomings in older Windows versions, using + &product-name; on Windows versions older than Vista with + Service Pack 1 is not recommended. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="security-encryption"> + + <title>Encryption</title> + + <para> + The following components of &product-name; use encryption to + protect sensitive data: + </para> + + <itemizedlist> + + <listitem> + <para> + When using the &product-name; Extension Pack provided by + Oracle for VRDP remote desktop support, RDP data can + optionally be encrypted. See <xref linkend="vrde-crypt" />. + Only the Enhanced RDP Security method (RDP5.2) with TLS + protocol provides a secure connection. Standard RDP Security + (RDP4 and RDP5.1) is vulnerable to a man-in-the-middle + attack. + </para> + </listitem> + + <listitem> + <para> + When using the &product-name; Extension Pack provided by + Oracle for disk encryption, the data stored in disk images + can optionally be encrypted. See + <xref linkend="diskencryption" />. This feature covers disk + image content only. All other data for a virtual machine is + stored unencrypted, including the VM's memory and device + state which is stored as part of a saved state, both when + created explicitly or part of a snapshot of a running VM. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + </sect1> + +<!-- + <sect1 id="security-devel"> + <title>Security Considerations for Developers</title> + </sect1> + --> + + <sect1 id="security-recommendations"> + + <title>Security Recommendations</title> + + <para> + This section contains security recommendations for specific + issues. By default VirtualBox will configure the VMs to run in a + secure manner, however this may not always be possible without + additional user actions such as host OS or firmware configuration + changes. + </para> + + <sect2 id="sec-rec-cve-2018-3646"> + + <title>CVE-2018-3646</title> + + <para> + This security issue affect a range of Intel CPUs with nested + paging. AMD CPUs are expected not to be impacted (pending direct + confirmation by AMD). Also the issue does not affect VMs running + with hardware virtualization disabled or with nested paging + disabled. + </para> + + <para> + For more information about nested paging, see + <xref linkend="nestedpaging" />. + </para> + + <para> + The following mitigation options are available. + </para> + + <sect3> + + <title>Disable Nested Paging</title> + + <para> + By disabling nested paging (EPT), the VMM will construct page + tables shadowing the ones in the guest. It is no possible for + the guest to insert anything fishy into the page tables, since + the VMM carefully validates each entry before shadowing it. + </para> + + <para> + As a side effect of disabling nested paging, several CPU + features will not be made available to the guest. Among these + features are AVX, AVX2, XSAVE, AESNI, and POPCNT. Not all + guests may be able to cope with dropping these features after + installation. Also, for some guests, especially in SMP + configurations, there could be stability issues arising from + disabling nested paging. Finally, some workloads may + experience a performance degradation. + </para> + + </sect3> + + <sect3> + + <title>Flushing the Level 1 Data Cache</title> + + <para> + This aims at removing potentially sensitive data from the + level 1 data cache when running guest code. However, it is + made difficult by hyper-threading setups sharing the level 1 + cache and thereby potentially letting the other thread in a + pair refill the cache with data the user does not want the + guest to see. In addition, flushing the level 1 data cache is + usually not without performance side effects. + </para> + + <para> + Up to date CPU microcode is a prerequisite for the cache + flushing mitigations. Some host OSes may install these + automatically, though it has traditionally been a task best + performed by the system firmware. So, please check with your + system / mainboard manufacturer for the latest firmware + update. + </para> + + <para> + We recommend disabling hyper threading on the host. This is + traditionally done from the firmware setup, but some OSes also + offers ways disable HT. In some cases it may be disabled by + default, but please verify as the effectiveness of the + mitigation depends on it. + </para> + + <para> + The default action taken by VirtualBox is to flush the level 1 + data cache when a thread is scheduled to execute guest code, + rather than on each VM entry. This reduces the performance + impact, while making the assumption that the host OS will not + handle security sensitive data from interrupt handlers and + similar without taking precautions. + </para> + + <para> + A more aggressive flushing option is provided via the + <command>VBoxManage modifyvm</command> + <option>--l1d-flush-on-vm-entry</option> option. When enabled + the level 1 data cache will be flushed on every VM entry. The + performance impact is greater than with the default option, + though this of course depends on the workload. Workloads + producing a lot of VM exits (like networking, VGA access, and + similiar) will probably be most impacted. + </para> + + <para> + For users not concerned by this security issue, the default + mitigation can be disabled using the <command>VBoxManage + modifyvm name --l1d-flush-on-sched off</command> command. + </para> + + </sect3> + + </sect2> + + <sect2 id="sec-rec-cve-2018-12126-et-al"> + + <title>CVE-2018-12126, CVE-2018-12127, CVE-2018-12130, CVE-2019-11091</title> + + <para> + These security issues affect a range of Intel CPUs starting with + Nehalem. The CVE-2018-12130 also affects some Atom Silvermont, + Atom Airmont, and Knights family CPUs, however the scope is so + limited that the host OS should deal with it and &product-name; + is therefore not affected. Leaks only happens when entering and + leaving C states. + </para> + + <para> + The following mitigation option is available. + </para> + + <sect3> + + <title>Buffer Overwriting and Disabling Hyper-Threading</title> + + <para> + First, up to date CPU microcode is a prerequisite for the + buffer overwriting (clearing) mitigations. Some host OSes may + install these automatically, though it has traditionally been + a task best performed by the system firmware. Please check + with your system or mainboard manufacturer for the latest + firmware update. + </para> + + <para> + This mitigation aims at removing potentially sensitive data + from the affected buffers before running guest code. Since + this means additional work each time the guest is scheduled, + there might be some performance side effects. + </para> + + <para> + We recommend disabling hyper-threading (HT) on hosts affected + by CVE-2018-12126 and CVE-2018-12127, because the affected + sets of buffers are normally shared between thread pairs and + therefore cause leaks between the threads. This is + traditionally done from the firmware setup, but some OSes also + offers ways disable HT. In some cases it may be disabled by + default, but please verify as the effectiveness of the + mitigation depends on it. + </para> + + <para> + The default action taken by &product-name; is to clear the + affected buffers when a thread is scheduled to execute guest + code, rather than on each VM entry. This reduces the + performance impact, while making the assumption that the host + OS will not handle security sensitive data from interrupt + handlers and similar without taking precautions. + </para> + + <para> + The <command>VBoxManage modifyvm</command> command provides a + more aggressive flushing option is provided by means of the + <option>--mds-clear-on-vm-entry</option> option. When enabled + the affected buffers will be cleared on every VM entry. The + performance impact is greater than with the default option, + though this of course depends on the workload. Workloads + producing a lot of VM exits (like networking, VGA access, and + similiar) will probably be most impacted. + </para> + + <para> + For users not concerned by this security issue, the default + mitigation can be disabled using the <command>VBoxManage + modifyvm name --mds-clear-on-sched off</command> command. + </para> + + </sect3> + + </sect2> + + </sect1> + +</chapter> diff --git a/doc/manual/en_US/user_Storage.xml b/doc/manual/en_US/user_Storage.xml new file mode 100644 index 00000000..95d4352e --- /dev/null +++ b/doc/manual/en_US/user_Storage.xml @@ -0,0 +1,2112 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="storage"> + + <title>Virtual Storage</title> + + <para> + As the virtual machine will most probably expect to see a hard disk + built into its virtual computer, &product-name; must be able to + present real storage to the guest as a virtual hard disk. There are + presently three methods by which to achieve this: + </para> + + <itemizedlist> + + <listitem> + <para> + &product-name; can use large image files on a real hard disk and + present them to a guest as a virtual hard disk. This is the most + common method, described in <xref linkend="vdidetails" />. + </para> + </listitem> + + <listitem> + <para> + iSCSI storage servers can be attached to &product-name;. This is + described in <xref linkend="storage-iscsi" />. + </para> + </listitem> + + <listitem> + <para> + You can allow a virtual machine to access one of your host disks + directly. This is an advanced feature, described in + <xref linkend="rawdisk" />. + </para> + </listitem> + + </itemizedlist> + + <para> + Each such virtual storage device, such as an image file, iSCSI + target, or physical hard disk, needs to be connected to the virtual + hard disk controller that &product-name; presents to a virtual + machine. This is explained in the next section. + </para> + + <sect1 id="harddiskcontrollers"> + + <title>Hard Disk Controllers</title> + + <para> + In a computing device, hard disks and CD/DVD drives are connected + to a device called a hard disk controller, which drives hard disk + operation and data transfers. &product-name; can emulate the most + common types of hard disk controllers typically found in computing + devices: IDE, SATA (AHCI), SCSI, SAS, USB-based, NVMe and + virtio-scsi mass storage devices. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">IDE (ATA)</emphasis> controllers are a + backwards-compatible yet very advanced extension of the disk + controller in the IBM PC/AT (1984). Initially, this interface + worked only with hard disks, but was later extended to also + support CD-ROM drives and other types of removable media. In + physical PCs, this standard uses flat ribbon parallel cables + with 40 or 80 wires. Each such cable can connect two devices, + called device 0 and device 1, to a controller. Typical PCs had + two connectors for such cables. As a result, support for up to + four IDE devices was most common: primary device 0, primary + device 1, secondary device 0, and secondary device 1. + </para> + + <para> + In &product-name;, each virtual machine may have one IDE + controller enabled, which gives you up to four virtual storage + devices that you can attach to the machine. By default, one of + these virtual storage devices, device 0 on the secondary + channel, is preconfigured to be the virtual machine's virtual + CD/DVD drive. However, you can change the default setting. + </para> + + <para> + Even if your guest OS has no support for SCSI or SATA devices, + it should always be able to see an IDE controller. + </para> + + <para> + You can also select which exact type of IDE controller + hardware &product-name; should present to the virtual machine: + PIIX3, PIIX4, or ICH6. This makes no difference in terms of + performance, but if you import a virtual machine from another + virtualization product, the OS in that machine may expect a + particular controller type and crash if it is not found. + </para> + + <para> + After you have created a new virtual machine with the + <emphasis role="bold">New Virtual Machine</emphasis> wizard in + &vbox-mgr;, you will typically see one IDE controller in the + machine's <emphasis role="bold">Storage</emphasis> settings. + The virtual CD/DVD drive will be attached to one of the four + ports of this controller. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Serial ATA (SATA)</emphasis> is a more + recent standard than IDE. Compared to IDE, it supports both + much higher speeds and more devices per controller. Also, with + physical hardware, devices can be added and removed while the + system is running. The standard interface for SATA controllers + is called Advanced Host Controller Interface (AHCI). + </para> + + <para> + Like a real SATA controller, &product-name;'s virtual SATA + controller operates faster and also consumes fewer CPU + resources than the virtual IDE controller. Also, this enables + you to connect up to 30 virtual hard disks to one machine + instead of just three, when compared to the &product-name; IDE + controller with a DVD drive attached. + </para> + + <para> + For this reason, depending on the selected guest OS, + &product-name; uses SATA as the default for newly created + virtual machines. One virtual SATA controller is created by + default, and the default disk that is created with a new VM is + attached to this controller. + </para> + + <warning> + <para> + The entire SATA controller and the virtual disks attached to + it, including those in IDE compatibility mode, will not be + seen by OSes that do not have device support for AHCI. In + particular, <emphasis>there is no support for AHCI in + Windows versions before Windows Vista</emphasis>. Legacy + Windows versions such as Windows XP, even with SP3 + installed, will not see such disks unless you install + additional drivers. It is possible to switch from IDE to + SATA after installation by installing the SATA drivers and + changing the controller type in the VM + <emphasis role="bold">Settings</emphasis> window. + </para> + + <para> + &product-name; recommends the Intel Matrix Storage drivers, + which can be downloaded from + <ulink url="http://downloadcenter.intel.com/Product_Filter.aspx?ProductID=2101" />. + </para> + </warning> + + <para> + To add a SATA controller to a machine for which it has not + been enabled by default, either because it was created by an + earlier version of &product-name;, or because SATA is not + supported by default by the selected guest OS, do the + following. Go to the <emphasis role="bold">Storage</emphasis> + page of the machine's + <emphasis role="bold">Settings</emphasis> window, click + <emphasis role="bold">Add Controller</emphasis> under the + Storage Tree box and then select <emphasis role="bold">Add + SATA Controller</emphasis>. The new controller appears as a + separate PCI device in the virtual machine, and you can add + virtual disks to it. + </para> + + <para> + To change the IDE compatibility mode settings for the SATA + controller, see <xref linkend="vboxmanage-storagectl" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">SCSI</emphasis> is another established + industry standard, standing for Small Computer System + Interface. SCSI is as a generic interface for data transfer + between all kinds of devices, including storage devices. SCSI + is still used for connecting some hard disks and tape devices, + but it has mostly been displaced in commodity hardware. It is + still in common use in high-performance workstations and + servers. + </para> + + <para> + Primarily for compatibility with other virtualization + software, &product-name; optionally supports LSI Logic and + BusLogic SCSI controllers, to each of which up to fifteen + virtual hard disks can be attached. + </para> + + <para> + To enable a SCSI controller, on the + <emphasis role="bold">Storage</emphasis> page of a virtual + machine's <emphasis role="bold">Settings</emphasis> window, + click <emphasis role="bold">Add Controller</emphasis> under + the Storage Tree box and then select <emphasis role="bold">Add + SCSI Controller</emphasis>. The new controller appears as a + separate PCI device in the virtual machine. + </para> + + <warning> + <para> + As with the other controller types, a SCSI controller will + only be seen by OSes with device support for it. Windows + 2003 and later ships with drivers for the LSI Logic + controller, while Windows NT 4.0 and Windows 2000 ships with + drivers for the BusLogic controller. Windows XP ships with + drivers for neither. + </para> + </warning> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Serial Attached SCSI (SAS)</emphasis> is + another bus standard which uses the SCSI command set. As + opposed to SCSI physical devices, serial cables are used + instead of parallel cables. This simplifies physical device + connections. In some ways, therefore, SAS is to SCSI what SATA + is to IDE: it enables more reliable and faster connections. + </para> + + <para> + To support high-end guests which require SAS controllers, + &product-name; emulates a LSI Logic SAS controller, which can + be enabled much the same way as a SCSI controller. At this + time, up to 255 devices can be connected to the SAS + controller. + </para> + + <warning> + <para> + As with SATA, the SAS controller will only be seen by OSes + with device support for it. In particular, <emphasis>there + is no support for SAS in Windows before Windows + Vista</emphasis>. So Windows XP, even SP3, will not see such + disks unless you install additional drivers. + </para> + </warning> + </listitem> + + <listitem> + <para> + The <emphasis role="bold">USB mass storage device + class</emphasis> is a standard to connect external storage + devices like hard disks or flash drives to a host through USB. + All major OSes support these devices and ship generic drivers + making third-party drivers superfluous. In particular, legacy + OSes without support for SATA controllers may benefit from USB + mass storage devices. + </para> + + <para> + The virtual USB storage controller offered by &product-name; + works differently to the other storage controller types. While + most storage controllers appear as a single PCI device to the + guest with multiple disks attached to it, the USB-based + storage controller does not appear as virtual storage + controller. Each disk attached to the controller appears as a + dedicated USB device to the guest. + </para> + + <warning> + <para> + Booting from drives attached using USB is only supported + when EFI is used as the BIOS lacks USB support. + </para> + </warning> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Non volatile memory express + (NVMe)</emphasis> is a standard for connecting non volatile + memory (NVM) directly over PCI Express to lift the bandwidth + limitation of the previously used SATA protocol for + solid-state devices. Unlike other standards the command set is + very simple in order to achieve maximum throughput and is not + compatible with ATA or SCSI. OSes need to support NVMe devices + to make use of them. For example, Windows 8.1 added native + NVMe support. For Windows 7, native support was added with an + update. + </para> + + <para> + The NVMe controller is part of the extension pack. + </para> + + <warning> + <para> + Booting from drives attached using NVMe is only supported + when EFI is used as the BIOS lacks the appropriate driver. + </para> + </warning> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Virtual I/O Device SCSI</emphasis> is a + standard to connect virtual storage devices like hard disks or + optical drives to a VM. Recent Linux and Windows versions + support these devices, but Windows needs additional drivers. + Currently virtio-scsi controller support is experimental. + </para> + + <warning> + <para> + The virtio-scsi controller will only be seen by OSes with + device support for it. In particular, <emphasis>there is no + built-in support in Windows</emphasis>. So Windows will not + see such disks unless you install additional drivers. + </para> + </warning> + </listitem> + + </itemizedlist> + + <para> + In summary, &product-name; gives you the following categories of + virtual storage slots: + </para> + + <itemizedlist> + + <listitem> + <para> + Four slots attached to the traditional IDE controller, which + are always present. One of these is typically a virtual CD/DVD + drive. + </para> + </listitem> + + <listitem> + <para> + 30 slots attached to the SATA controller, if enabled and + supported by the guest OS. + </para> + </listitem> + + <listitem> + <para> + 15 slots attached to the SCSI controller, if enabled and + supported by the guest OS. + </para> + </listitem> + + <listitem> + <para> + Up to 255 slots attached to the SAS controller, if enabled and + supported by the guest OS. + </para> + </listitem> + + <listitem> + <para> + Eight slots attached to the virtual USB controller, if enabled + and supported by the guest OS. + </para> + </listitem> + + <listitem> + <para> + Up to 255 slots attached to the NVMe controller, if enabled + and supported by the guest OS. + </para> + </listitem> + + <listitem> + <para> + Up to 256 slots attached to the virtio-scsi controller, if + enabled and supported by the guest OS. + </para> + </listitem> + + </itemizedlist> + + <para> + Given this large choice of storage controllers, you may not know + which one to choose. In general, you should avoid IDE unless it is + the only controller supported by your guest. Whether you use SATA, + SCSI, or SAS does not make any real difference. The variety of + controllers is only supplied by &product-name; for compatibility + with existing hardware and other hypervisors. + </para> + + </sect1> + + <sect1 id="vdidetails"> + + <title>Disk Image Files (VDI, VMDK, VHD, HDD)</title> + + <para> + Disk image files reside on the host system and are seen by the + guest systems as hard disks of a certain geometry. When a guest OS + reads from or writes to a hard disk, &product-name; redirects the + request to the image file. + </para> + + <para> + Like a physical disk, a virtual disk has a size, or capacity, + which must be specified when the image file is created. As opposed + to a physical disk however, &product-name; enables you to expand + an image file after creation, even if it has data already. See + <xref linkend="vboxmanage-modifymedium" />. + </para> + + <para> + &product-name; supports the following types of disk image files: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">VDI.</emphasis> Normally, &product-name; + uses its own container format for guest hard disks. This is + called a Virtual Disk Image (VDI) file. This format is used + when you create a new virtual machine with a new disk. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VMDK.</emphasis> &product-name; also + fully supports the popular and open VMDK container format that + is used by many other virtualization products, such as VMware. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VHD.</emphasis> &product-name; also + fully supports the VHD format used by Microsoft. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">HDD.</emphasis> Image files of Parallels + version 2 (HDD format) are also supported. + </para> + + <para> + Due to lack of documentation of the format, newer versions + such as 3 and 4 are not supported. You can however convert + such image files to version 2 format using tools provided by + Parallels. + </para> + </listitem> + + </itemizedlist> + + <para> + Irrespective of the disk capacity and format, as mentioned in + <xref linkend="create-vm-wizard" />, there are two options for + creating a disk image: fixed-size or dynamically allocated. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Fixed-size.</emphasis> If you create a + fixed-size image, an image file will be created on your host + system which has roughly the same size as the virtual disk's + capacity. So, for a 10 GB disk, you will have a 10 GB file. + Note that the creation of a fixed-size image can take a long + time depending on the size of the image and the write + performance of your hard disk. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Dynamically allocated.</emphasis> For + more flexible storage management, use a dynamically allocated + image. This will initially be very small and not occupy any + space for unused virtual disk sectors, but will grow every + time a disk sector is written to for the first time, until the + drive reaches the maximum capacity chosen when the drive was + created. While this format takes less space initially, the + fact that &product-name; needs to expand the image file + consumes additional computing resources, so until the disk + file size has stabilized, write operations may be slower than + with fixed size disks. However, after a time the rate of + growth will slow and the average penalty for write operations + will be negligible. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="virtual-media-manager"> + + <title>The Virtual Media Manager</title> + + <para> + &product-name; keeps track of all the hard disk, CD/DVD-ROM, and + floppy disk images which are in use by virtual machines. These are + often referred to as <emphasis>known media</emphasis> and come + from two sources: + </para> + + <itemizedlist> + + <listitem> + <para> + All media currently attached to virtual machines. + </para> + </listitem> + + <listitem> + <para> + Registered media, for compatibility with legacy &product-name; + versions. + </para> + </listitem> + + </itemizedlist> + + <para> + The known media can be viewed and changed using the + <emphasis role="bold">Virtual Media Manager</emphasis> tool, which + you access by clicking <emphasis role="bold">Media</emphasis> on + the global <emphasis role="bold">Tools</emphasis> menu in + &vbox-mgr;. + </para> + + <figure id="fig-virtual-media-manager"> + <title>The Virtual Media Manager, Showing Hard Disk Images</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/virtual-disk-manager.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The known media are conveniently grouped in separate tabs for the + supported formats. These formats are: + </para> + + <itemizedlist> + + <listitem> + <para> + Hard disk images, either in &product-name;'s own Virtual Disk + Image (VDI) format, or in the third-party formats listed in + <xref linkend="vdidetails"/>. + </para> + </listitem> + + <listitem> + <para> + CD/DVD images in standard ISO format. + </para> + </listitem> + + <listitem> + <para> + Floppy images in standard RAW format. + </para> + </listitem> + + </itemizedlist> + + <para> + For each image, the Virtual Media Manager shows you the full path + of the image file and other information, such as the virtual + machine the image is currently attached to. + </para> + + <para> + The Virtual Media Manager enables you to do the following: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Add</emphasis> an image to the known + media. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Create</emphasis> a new disk image. + </para> + + <itemizedlist> + + <listitem> + <para> + For hard disks, the <emphasis role="bold">Create Virtual + Hard Disk</emphasis> wizard is shown. See + <xref linkend="create-virtual-hard-disk-image"/>. + </para> + </listitem> + + <listitem> + <para> + For optical disks, the <emphasis role="bold">VISO + Creator</emphasis> tool is shown. See + <xref linkend="create-optical-disk-image"/>. + </para> + </listitem> + + <listitem> + <para> + For floppy disks, the <emphasis role="bold">Floppy Disk + Creator</emphasis> tool is shown. See + <xref linkend="create-floppy-disk-image"/>. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Copy</emphasis> an image to create + another one. + </para> + + <para> + For virtual hard disks, you can specify one of the following + target types: VDI, VHD, or VMDK. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Move</emphasis> an image to another + location. + </para> + + <para> + A file dialog prompts you for the new image file location. + </para> + + <para> + When you use the Virtual Media Manager to move a disk image, + &product-name; updates all related configuration files + automatically. + </para> + + <note> + <para> + Always use the Virtual Media Manager or the + <command>VBoxManage modifymedium</command> command to move a + disk image. + </para> + + <para> + If you use a file management feature of the host OS to move + a disk image to a new location, run the <command>VBoxManage + modifymedium</command> <option>--setlocation</option> + command to configure the new path of the disk image on the + host file system. This command updates the &product-name; + configuration automatically. + </para> + </note> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Remove</emphasis> an image from the + known media. You can optionally delete the image file when + removing the image. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Release</emphasis> an image to detach it + from a VM. This action only applies if the image is currently + attached to a VM as a virtual hard disk. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Clear</emphasis> all inaccessible disk + images from the list. The disk images are released from the + VMs they are attached to and removed from the known media. + </para> + + <note> + <para> + This option is for optical disks and floppy disks only. + </para> + </note> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Search</emphasis> for an image by name + or UUID. + </para> + </listitem> + + <listitem> + <para> + View and edit the <emphasis role="bold">Properties</emphasis> + of a disk image. + </para> + + <para> + Available properties include the following: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Type:</emphasis> Specifies the + snapshot behavior of the disk. See + <xref linkend="hdimagewrites"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Location:</emphasis> Specifies the + location of the disk image file on the host system. You + can use a file dialog to browse for the disk image + location. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Description:</emphasis> Specifies a + short description of the disk image. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Size:</emphasis> Specifies the size + of the disk image. You can use the slider to increase or + decrease the disk image size. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Information:</emphasis> Specifies + detailed information about the disk image. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Refresh</emphasis> the property values + of the selected disk image. + </para> + </listitem> + + </itemizedlist> + + <para> + To perform these actions, highlight the medium in the Virtual + Media Manager and then do one of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Click an icon in the Virtual Media Manager toolbar. + </para> + </listitem> + + <listitem> + <para> + Right-click the medium and select an option. + </para> + </listitem> + + </itemizedlist> + + <para> + Use the <emphasis role="bold">Storage</emphasis> page in a VM's + <emphasis role="bold">Settings</emphasis> window to create a new + disk image. By default, disk images are stored in the VM's folder. + </para> + + <para> + You can copy hard disk image files to other host systems and then + import them in to VMs from the host system. However, some Windows + guest OSes may require that you configure the new VM in a similar + way to the old one. + </para> + + <note> + <para> + Do not simply make copies of virtual disk images. If you import + such a second copy into a VM, &product-name; issues an error + because &product-name; assigns a universally unique identifier + (UUID) to each disk image to ensure that it is only used one + time. See <xref linkend="cloningvdis" />. Also, if you want to + copy a VM to another system, use the &product-name; import and + export features. See <xref linkend="ovf" />. + </para> + </note> + + <sect2 id="create-virtual-hard-disk-image"> + + <title>Creating a Virtual Hard Disk Image</title> + + <para> + Use the <emphasis role="bold">Create Virtual Hard + Disk</emphasis> wizard to create a hard disk image. + </para> + + <orderedlist> + + <listitem> + <para> + Display the <emphasis role="bold">Hard Disks</emphasis> tab + in Virtual Media Manager and click + <emphasis role="bold">Create</emphasis>. + </para> + + <para> + The <emphasis role="bold">Create Virtual Hard + Disk</emphasis> wizard is shown. + </para> + + <figure id="fig-virtual-hard-disk-wizard"> + <title>Create Virtual Hard Disk Wizard</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/virtual-hard-disk-wizard.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + </listitem> + + <listitem> + <para> + On the <emphasis role="bold">Virtual Hard Disk File + Type</emphasis> page, select a file type for the new virtual + hard disk image. + </para> + + <para> + Click <emphasis role="bold">Next</emphasis>. + </para> + </listitem> + + <listitem> + <para> + On the <emphasis role="bold">Storage on Physical Hard + Disk</emphasis> page, select whether the size of the virtual + hard disk file is dynamically allocated or is of fixed size. + </para> + + <para> + Click <emphasis role="bold">Next</emphasis>. + </para> + </listitem> + + <listitem> + <para> + On the <emphasis role="bold">File Location and + Size</emphasis> page, configure the location of the virtual + hard disk file and use the slider to set the size limit for + the virtual hard disk. + </para> + + <para> + Click <emphasis role="bold">Finish</emphasis> to create the + virtual hard disk file. + </para> + + <para> + The virtual hard disk image is created in the specified + location and added to the <emphasis role="bold">Hard + Disks</emphasis> tab in Virtual Media Manager. + </para> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="create-optical-disk-image"> + + <title>Creating a Virtual Optical Disk Image</title> + + <para> + Use the <emphasis role="bold">VISO Creator</emphasis> tool to + create a virtual optical disk image. This enables you to create + a virtual ISO from selected files on the host. + </para> + + <orderedlist> + + <listitem> + <para> + Display the <emphasis role="bold">Optical Disks</emphasis> + tab in Virtual Media Manager and click + <emphasis role="bold">Create</emphasis>. + </para> + + <para> + The <emphasis role="bold">VISO Creator</emphasis> tool is + shown. + </para> + </listitem> + + <listitem> + <para> + Create the virtual ISO file. + </para> + + <orderedlist> + + <listitem> + <para> + Configure the name of the ISO file. + </para> + + <para> + Click <emphasis role="bold">Configuration</emphasis> and + enter a name in the <emphasis role="bold">Viso + Name</emphasis> field. + </para> + </listitem> + + <listitem> + <para> + Add files to your virtual ISO. + </para> + + <para> + In the <emphasis role="bold">Host File System</emphasis> + pane, select files to copy from the host system to the + virtual ISO. + </para> + + <para> + Click <emphasis role="bold">Add Items To + VISO</emphasis>. The files are displayed in the + <emphasis role="bold">VISO Content</emphasis> pane. + </para> + + <para> + The following file operations are also available: + </para> + + <itemizedlist> + + <listitem> + <para> + To create folders on the virtual ISO, click + <emphasis role="bold">Create New + Directory</emphasis>. + </para> + </listitem> + + <listitem> + <para> + To remove files from the virtual ISO, select files + in the <emphasis role="bold">VISO Content</emphasis> + pane and click <emphasis role="bold">Remove Items + From VISO</emphasis>. + </para> + </listitem> + + <listitem> + <para> + To remove <emphasis>all</emphasis> files from the + virtual ISO, click <emphasis role="bold">Reset the + VISO Content</emphasis>. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </orderedlist> + </listitem> + + <listitem> + <para> + Create the virtual ISO image. + </para> + + <para> + Click <emphasis role="bold">Create</emphasis>. + </para> + + <para> + A virtual ISO file with the specified name and content is + created. + </para> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="create-floppy-disk-image"> + + <title>Creating a Virtual Floppy Disk Image</title> + + <para> + Use the <emphasis role="bold">Floppy Disk Creator</emphasis> + tool to create a floppy disk image. + </para> + + <orderedlist> + + <listitem> + <para> + Display the <emphasis role="bold">Floppy Disks</emphasis> + tab in Virtual Media Manager and click + <emphasis role="bold">Create</emphasis>. + </para> + + <para> + The <emphasis role="bold">Floppy Disk Creator</emphasis> + tool is shown. + </para> + </listitem> + + <listitem> + <para> + Configure the following settings: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">File Path:</emphasis> The name and + location of the floppy disk image. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Size:</emphasis> Select from the + list of supported floppy disk sizes. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Format Disk as FAT 12:</emphasis> + This is the default format used for most floppy disks. + For an unformatted disk, do not select this option. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Create the floppy disk image file. + </para> + + <para> + Click <emphasis role="bold">Create</emphasis>. + </para> + + <para> + The floppy disk image is created in the specified location + and added to the <emphasis role="bold">Floppy + Disks</emphasis> tab in Virtual Media Manager. + </para> + </listitem> + + </orderedlist> + + </sect2> + + </sect1> + + <sect1 id="hdimagewrites"> + + <title>Special Image Write Modes</title> + + <para> + For each virtual disk image supported by &product-name;, you can + determine separately how it should be affected by write operations + from a virtual machine and snapshot operations. This applies to + all of the aforementioned image formats (VDI, VMDK, VHD, or HDD) + and irrespective of whether an image is fixed-size or dynamically + allocated. + </para> + + <para> + By default, images are in <emphasis>normal</emphasis> mode. To + mark an existing image with one of the non-standard modes listed + below, use <command>VBoxManage modifymedium</command>. See + <xref linkend="vboxmanage-modifymedium" />. Alternatively, use + <command>VBoxManage storageattach</command> to attach the image to + a VM and specify the <option>--mtype</option> argument. See + <xref linkend="vboxmanage-storageattach" />. + </para> + + <para> + The available virtual disk image modes are as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Normal images</emphasis> have no + restrictions on how guests can read from and write to the + disk. This is the default image mode. + </para> + + <para> + When you take a snapshot of your virtual machine as described + in <xref linkend="snapshots" />, the state of a normal hard + disk is recorded together with the snapshot, and when + reverting to the snapshot, its state will be fully reset. + </para> + + <para> + The image file itself is not reset. Instead, when a snapshot + is taken, &product-name; <emphasis>freezes</emphasis> the + image file and no longer writes to it. For the write + operations from the VM, a second, + <emphasis>differencing</emphasis> image file is created which + receives only the changes to the original image. See + <xref linkend="diffimages"/>. + </para> + + <para> + While you can attach the same normal image to more than one + virtual machine, only one of these virtual machines attached + to the same image file can be executed simultaneously, as + otherwise there would be conflicts if several machines write + to the same image file. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Write-through hard disks</emphasis> are + completely unaffected by snapshots. Their state is + <emphasis>not</emphasis> saved when a snapshot is taken, and + not restored when a snapshot is restored. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Shareable hard disks</emphasis> are a + variant of write-through hard disks. In principle they behave + exactly the same. Their state is <emphasis>not</emphasis> + saved when a snapshot is taken, and not restored when a + snapshot is restored. The difference only shows if you attach + such disks to several VMs. Shareable disks may be attached to + several VMs which may run concurrently. This makes them + suitable for use by cluster filesystems between VMs and + similar applications which are explicitly prepared to access a + disk concurrently. Only fixed size images can be used in this + way, and dynamically allocated images are rejected. + </para> + + <warning> + <para> + This is an expert feature, and misuse can lead to data loss, + as regular filesystems are not prepared to handle + simultaneous changes by several parties. + </para> + </warning> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Immutable images</emphasis> only + remember write accesses temporarily while the virtual machine + is running. All changes are lost when the virtual machine is + powered on the next time. As a result, as opposed to Normal + images, the same immutable image can be used with several + virtual machines without restrictions. + </para> + + <para> + Creating an immutable image makes little sense since it would + be initially empty and lose its contents with every machine + restart. You would have a disk that is always unformatted when + the machine starts up. Instead, you can first create a normal + image and then later mark it as immutable when you decide that + the contents are useful. + </para> + + <para> + If you take a snapshot of a machine with immutable images, + then on every machine power-up, those images are reset to the + state of the last (current) snapshot, instead of the state of + the original immutable image. + </para> + + <note> + <para> + As a special exception, immutable images are + <emphasis>not</emphasis> reset if they are attached to a + machine in a saved state or whose last snapshot was taken + while the machine was running. This is called an + <emphasis>online snapshot</emphasis>. As a result, if the + machine's current snapshot is an online snapshot, its + immutable images behave exactly like the a normal image. To + reenable the automatic resetting of such images, delete the + current snapshot of the machine. + </para> + </note> + + <para> + &product-name; never writes to an immutable image directly at + all. All write operations from the machine are directed to a + differencing image. The next time the VM is powered on, the + differencing image is reset so that every time the VM starts, + its immutable images have exactly the same content. + </para> + + <para> + The differencing image is only reset when the machine is + powered on from within &product-name;, not when you reboot by + requesting a reboot from within the machine. This is also why + immutable images behave as described above when snapshots are + also present, which use differencing images as well. + </para> + + <para> + If the automatic discarding of the differencing image on VM + startup does not fit your needs, you can turn it off using the + <option>autoreset</option> parameter of <command>VBoxManage + modifymedium</command>. See + <xref linkend="vboxmanage-modifymedium"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Multiattach mode images</emphasis> can + be attached to more than one virtual machine at the same time, + even if these machines are running simultaneously. For each + virtual machine to which such an image is attached, a + differencing image is created. As a result, data that is + written to such a virtual disk by one machine is not seen by + the other machines to which the image is attached. Each + machine creates its own write history of the multiattach + image. + </para> + + <para> + Technically, a multiattach image behaves identically to an + immutable image except the differencing image is not reset + every time the machine starts. + </para> + + <para> + This mode is useful for sharing files which are almost never + written, for instance picture galleries, where every guest + changes only a small amount of data and the majority of the + disk content remains unchanged. The modified blocks are stored + in differencing images which remain relatively small and the + shared content is stored only once at the host. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Read-only images</emphasis> are used + automatically for CD/DVD images, since CDs/DVDs can never be + written to. + </para> + </listitem> + + </itemizedlist> + + <para> + The following scenario illustrates the differences between the + various image modes, with respect to snapshots. + </para> + + <para> + Assume you have installed your guest OS in your VM, and you have + taken a snapshot. Later, your VM is infected with a virus and you + would like to go back to the snapshot. With a normal hard disk + image, you simply restore the snapshot, and the earlier state of + your hard disk image will be restored as well and your virus + infection will be undone. With an immutable hard disk, all it + takes is to shut down and power on your VM, and the virus + infection will be discarded. With a write-through image however, + you cannot easily undo the virus infection by means of + virtualization, but will have to disinfect your virtual machine + like a real computer. + </para> + + <para> + You might find write-through images useful if you want to preserve + critical data irrespective of snapshots. As you can attach more + than one image to a VM, you may want to have one immutable image + for the OS and one write-through image for your data files. + </para> + + </sect1> + + <sect1 id="diffimages"> + + <title>Differencing Images</title> + + <para> + The previous section mentioned differencing images and how they + are used with snapshots, immutable images, and multiple disk + attachments. This section describes in more detail how + differencing images work. + </para> + + <para> + A differencing image is a special disk image that only holds the + differences to another image. A differencing image by itself is + useless, it must always refer to another image. The differencing + image is then typically referred to as a + <emphasis>child</emphasis>, which holds the differences to its + <emphasis>parent</emphasis>. + </para> + + <para> + When a differencing image is active, it receives all write + operations from the virtual machine instead of its parent. The + differencing image only contains the sectors of the virtual hard + disk that have changed since the differencing image was created. + When the machine reads a sector from such a virtual hard disk, it + looks into the differencing image first. If the sector is present, + it is returned from there. If not, &product-name; looks into the + parent. In other words, the parent becomes + <emphasis>read-only</emphasis>. It is never written to again, but + it is read from if a sector has not changed. + </para> + + <para> + Differencing images can be chained. If another differencing image + is created for a virtual disk that already has a differencing + image, then it becomes a <emphasis>grandchild</emphasis> of the + original parent. The first differencing image then becomes + read-only as well, and write operations only go to the + second-level differencing image. When reading from the virtual + disk, &product-name; needs to look into the second differencing + image first, then into the first if the sector was not found, and + then into the original image. + </para> + + <para> + There can be an unlimited number of differencing images, and each + image can have more than one child. As a result, the differencing + images can form a complex tree with parents, siblings, and + children, depending on how complex your machine configuration is. + Write operations always go to the one <emphasis>active</emphasis> + differencing image that is attached to the machine, and for read + operations, &product-name; may need to look up all the parents in + the chain until the sector in question is found. You can view such + a tree in the Virtual Media Manager. + </para> + + <figure id="fig-diff-images"> + <title>Differencing Images, Shown in Virtual Media Manager</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/virtual-disk-manager-2.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + In all of these situations, from the point of view of the virtual + machine, the virtual hard disk behaves like any other disk. While + the virtual machine is running, there is a slight run-time I/O + overhead because &product-name; might need to look up sectors + several times. This is not noticeable however since the tables + with sector information are always kept in memory and can be + looked up quickly. + </para> + + <para> + Differencing images are used in the following situations: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Snapshots.</emphasis> When you create a + snapshot, as explained in the previous section, &product-name; + <emphasis>freezes</emphasis> the images attached to the + virtual machine and creates differencing images for each image + that is not in <emphasis>write-through</emphasis> mode. From + the point of view of the virtual machine, the virtual disks + continue to operate before, but all write operations go into + the differencing images. Each time you create another + snapshot, for each hard disk attachment, another differencing + image is created and attached, forming a chain or tree. + </para> + + <para> + In the above screenshot, you see that the original disk image + is now attached to a snapshot, representing the state of the + disk when the snapshot was taken. + </para> + + <para> + If you <emphasis>restore</emphasis> a snapshot, and want to go + back to the exact machine state that was stored in the + snapshot, the following happens: + </para> + + <itemizedlist> + + <listitem> + <para> + &product-name; copies the virtual machine settings that + were copied into the snapshot back to the virtual machine. + As a result, if you have made changes to the machine + configuration since taking the snapshot, they are undone. + </para> + </listitem> + + <listitem> + <para> + If the snapshot was taken while the machine was running, + it contains a saved machine state, and that state is + restored as well. After restoring the snapshot, the + machine will then be in Saved state and resume execution + from there when it is next started. Otherwise the machine + will be in Powered Off state and do a full boot. + </para> + </listitem> + + <listitem> + <para> + For each disk image attached to the machine, the + differencing image holding all the write operations since + the current snapshot was taken is thrown away, and the + original parent image is made active again. If you + restored the root snapshot, then this will be the root + disk image for each attachment. Otherwise, some other + differencing image descended from it. This effectively + restores the old machine state. + </para> + </listitem> + + </itemizedlist> + + <para> + If you later <emphasis>delete</emphasis> a snapshot in order + to free disk space, for each disk attachment, one of the + differencing images becomes obsolete. In this case, the + differencing image of the disk attachment cannot simply be + deleted. Instead, &product-name; needs to look at each sector + of the differencing image and needs to copy it back into its + parent. This is called "merging" images and can be a + potentially lengthy process, depending on how large the + differencing image is. It can also temporarily need a + considerable amount of extra disk space, before the + differencing image obsoleted by the merge operation is + deleted. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Immutable images.</emphasis> When an + image is switched to immutable mode, a differencing image is + created as well. As with snapshots, the parent image then + becomes read-only, and the differencing image receives all the + write operations. Every time the virtual machine is started, + all the immutable images which are attached to it have their + respective differencing image thrown away, effectively + resetting the virtual machine's virtual disk with every + restart. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="cloningvdis"> + + <title>Cloning Disk Images</title> + + <para> + You can duplicate hard disk image files on the same host to + quickly produce a second virtual machine with the same OS setup. + However, you should <emphasis>only</emphasis> make copies of + virtual disk images using the utility supplied with + &product-name;. See <xref linkend="vboxmanage-clonemedium" />. + This is because &product-name; assigns a UUID to each disk image, + which is also stored inside the image, and &product-name; will + refuse to work with two images that use the same number. If you do + accidentally try to reimport a disk image which you copied + normally, you can make a second copy using the <command>VBoxManage + clonevm</command> command and import that instead. + </para> + + <para> + Note that Linux distributions identify the boot hard disk from the + ID of the drive. The ID &product-name; reports for a drive is + determined from the UUID of the virtual disk image. So if you + clone a disk image and try to boot the copied image the guest + might not be able to determine its own boot disk as the UUID + changed. In this case you have to adapt the disk ID in your boot + loader script, for example + <filename>/boot/grub/menu.lst</filename>. The disk ID looks like + the following: + </para> + +<screen>scsi-SATA_VBOX_HARDDISK_VB5cfdb1e2-c251e503</screen> + + <para> + The ID for the copied image can be determined as follows: + </para> + +<screen>hdparm -i /dev/sda</screen> + + </sect1> + + <sect1 id="iocaching"> + + <title>Host Input/Output Caching</title> + + <para> + &product-name; can optionally disable the I/O caching that the + host OS would otherwise perform on disk image files. + </para> + + <para> + Traditionally, &product-name; has opened disk image files as + normal files, which results in them being cached by the host OS + like any other file. The main advantage of this is speed: when the + guest OS writes to disk and the host OS cache uses delayed + writing, the write operation can be reported as completed to the + guest OS quickly while the host OS can perform the operation + asynchronously. Also, when you start a VM a second time and have + enough memory available for the OS to use for caching, large parts + of the virtual disk may be in system memory, and the VM can access + the data much faster. + </para> + + <para> + Note that this applies only to image files. Buffering does not + occur for virtual disks residing on remote iSCSI storage, which is + the more common scenario in enterprise-class setups. See + <xref linkend="storage-iscsi" />. + </para> + + <para> + While buffering is a useful default setting for virtualizing a few + machines on a desktop computer, there are some disadvantages to + this approach: + </para> + + <itemizedlist> + + <listitem> + <para> + Delayed writing through the host OS cache is less secure. When + the guest OS writes data, it considers the data written even + though it has not yet arrived on a physical disk. If for some + reason the write does not happen, such as power failure or + host crash, the likelihood of data loss increases. + </para> + </listitem> + + <listitem> + <para> + Disk image files tend to be very large. Caching them can + therefore quickly use up the entire host OS cache. Depending + on the efficiency of the host OS caching, this may slow down + the host immensely, especially if several VMs run at the same + time. For example, on Linux hosts, host caching may result in + Linux delaying all writes until the host cache is nearly full + and then writing out all these changes at once, possibly + stalling VM execution for minutes. This can result in I/O + errors in the guest as I/O requests time out there. + </para> + </listitem> + + <listitem> + <para> + Physical memory is often wasted as guest OSes typically have + their own I/O caches, which may result in the data being + cached twice, in both the guest and the host caches, for + little effect. + </para> + </listitem> + + </itemizedlist> + + <para> + If you decide to disable host I/O caching for the above reasons, + &product-name; uses its own small cache to buffer writes, but no + read caching since this is typically already performed by the + guest OS. In addition, &product-name; fully supports asynchronous + I/O for its virtual SATA, SCSI, and SAS controllers through + multiple I/O threads. + </para> + + <para> + Since asynchronous I/O is not supported by IDE controllers, for + performance reasons, you may want to leave host caching enabled + for your VM's virtual IDE controllers. + </para> + + <para> + For this reason, &product-name; enables you to configure whether + the host I/O cache is used for each I/O controller separately. + Either select the <emphasis role="bold">Use Host I/O + Cache</emphasis> check box in the + <emphasis role="bold">Storage</emphasis> settings for a given + virtual storage controller, or use the following + <command>VBoxManage</command> command to disable the host I/O + cache for a virtual storage controller: + </para> + +<screen>VBoxManage storagectl "VM name" --name <controllername> --hostiocache off</screen> + + <para> + See <xref linkend="vboxmanage-storagectl" />. + </para> + + <para> + For the above reasons, &product-name; uses SATA controllers by + default for new virtual machines. + </para> + + </sect1> + + <sect1 id="storage-bandwidth-limit"> + + <title>Limiting Bandwidth for Disk Images</title> + + <para> + &product-name; supports limiting of the maximum bandwidth used for + asynchronous I/O. Additionally it supports sharing limits through + bandwidth groups for several images. It is possible to have more + than one such limit. + </para> + + <para> + Limits are configured using <command>VBoxManage</command>. The + example below creates a bandwidth group named Limit, sets the + limit to 20 MB per second, and assigns the group to the attached + disks of the VM: + </para> + +<screen>VBoxManage bandwidthctl "VM name" add Limit --type disk --limit 20M +VBoxManage storageattach "VM name" --storagectl "SATA" --port 0 --device 0 --type hdd + --medium disk1.vdi --bandwidthgroup Limit +VBoxManage storageattach "VM name" --storagectl "SATA" --port 1 --device 0 --type hdd + --medium disk2.vdi --bandwidthgroup Limit</screen> + + <para> + All disks in a group share the bandwidth limit, meaning that in + the example above the bandwidth of both images combined can never + exceed 20 MBps. However, if one disk does not require bandwidth + the other can use the remaining bandwidth of its group. + </para> + + <para> + The limits for each group can be changed while the VM is running, + with changes being picked up immediately. The example below + changes the limit for the group created in the example above to 10 + MBps: + </para> + +<screen>VBoxManage bandwidthctl "VM name" set Limit --limit 10M</screen> + + </sect1> + + <sect1 id="storage-cds"> + + <title>CD/DVD Support</title> + + <para> + Virtual CD/DVD drives by default support only reading. The medium + configuration is changeable at runtime. You can select between the + following options to provide the medium data: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Host Drive</emphasis> defines that the + guest can read from the medium in the host drive. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Image file</emphasis> gives the guest + read-only access to the data in the image. This is typically + an ISO file. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Empty</emphasis> means a drive without + an inserted medium. + </para> + </listitem> + + </itemizedlist> + + <para> + Changing between the above, or changing a medium in the host drive + that is accessed by a machine, or changing an image file will + signal a medium change to the guest OS. The guest OS can then + react to the change, for example by starting an installation + program. + </para> + + <para> + Medium changes can be prevented by the guest, and &product-name; + reflects that by locking the host drive if appropriate. You can + force a medium removal in such situations by using the VirtualBox + Manager or the <command>VBoxManage</command> command line tool. + Effectively this is the equivalent of the emergency eject which + many CD/DVD drives provide, with all associated side effects. The + guest OS can issue error messages, just like on real hardware, and + guest applications may misbehave. Use this with caution. + </para> + + <note> + <para> + The identification string of the drive provided to the guest, + displayed by configuration tools such as the Windows Device + Manager, is always VBOX CD-ROM, irrespective of the current + configuration of the virtual drive. This is to prevent hardware + detection from being triggered in the guest OS every time the + configuration is changed. + </para> + </note> + + <para> + The standard CD/DVD emulation enables reading of standard data CD + and DVD formats only. As an experimental feature, for additional + capabilities, it is possible to give the guest direct access to + the CD/DVD host drive by enabling <emphasis>passthrough</emphasis> + mode. Depending on the host hardware, this may potentially enable + the following things to work: + </para> + + <itemizedlist> + + <listitem> + <para> + CD/DVD writing from within the guest, if the host DVD drive is + a CD/DVD writer + </para> + </listitem> + + <listitem> + <para> + Playing audio CDs + </para> + </listitem> + + <listitem> + <para> + Playing encrypted DVDs + </para> + </listitem> + + </itemizedlist> + + <para> + To enable host drive passthrough you can use the + <option>--passthrough</option> option of the <command>VBoxManage + storageattach</command> command. See + <xref linkend="vboxmanage-storageattach" />. + </para> + + <para> + Even if passthrough is enabled, unsafe commands, such as updating + the drive firmware, will be blocked. Video CD formats are never + supported, not even in passthrough mode, and cannot be played from + a virtual machine. + </para> + + <para> + On Oracle Solaris hosts, passthrough requires running + &product-name; with real root permissions due to security measures + enforced by the host. + </para> + + </sect1> + + <sect1 id="storage-iscsi"> + + <title>iSCSI Servers</title> + + <para> + iSCSI stands for <emphasis>Internet SCSI</emphasis> and is a + standard that supports use of the SCSI protocol over Internet + (TCP/IP) connections. Especially with the advent of Gigabit + Ethernet, it has become affordable to attach iSCSI storage servers + simply as remote hard disks to a computer network. In iSCSI + terminology, the server providing storage resources is called an + <emphasis>iSCSI target</emphasis>, while the client connecting to + the server and accessing its resources is called an + <emphasis>iSCSI initiator</emphasis>. + </para> + + <para> + &product-name; can transparently present iSCSI remote storage to a + virtual machine as a virtual hard disk. The guest OS will not see + any difference between a virtual disk image (VDI file) and an + iSCSI target. To achieve this, &product-name; has an integrated + iSCSI initiator. + </para> + + <para> + &product-name;'s iSCSI support has been developed according to the + iSCSI standard and should work with all standard-conforming iSCSI + targets. To use an iSCSI target with &product-name;, you must use + the command line. See <xref linkend="vboxmanage-storageattach" />. + </para> + + </sect1> + + <sect1 id="vboximg-mount"> + + <title>vboximg-mount: A Utility for FUSE Mounting a Virtual Disk Image</title> + + <para> + <command>vboximg-mount</command> is a command line utility for Mac + OS and Linux hosts that provides raw access to an &product-name; + virtual disk image on the host system. Use this utility to mount, + view, and optionally modify the disk image contents. + </para> + + <para> + The utility is based on Filesystem in Userspace (FUSE) technology + and uses the VirtualBox runtime engine. Ensure that &product-name; + is running on the host system. + </para> + + <note> + <para> + When using <command>vboximg-mount</command>, ensure that the + following conditions apply: + </para> + + <itemizedlist> + + <listitem> + <para> + The disk image is not being used by any other systems, such + as by guest VMs. + </para> + </listitem> + + <listitem> + <para> + No VMs are running on the host system. + </para> + </listitem> + + </itemizedlist> + </note> + + <para> + Raw access using FUSE is preferred over direct loopback mounting + of virtual disk images, because it is snapshot aware. It can + selectively merge disk differencing images in an exposed virtual + hard disk, providing historical or up-to-date representations of + the virtual disk contents. + </para> + + <para> + <command>vboximg-mount</command> enables you to view information + about registered VMs, their attached disk media, and any + snapshots. Also, you can view partition information for a disk + image. + </para> + + <para> + The <command>vboximg-mount </command>command includes experimental + read-only access to file systems inside a VM disk image. This + feature enables you to extract some files from the disk image + without starting the VM and without requiring third-party file + system drivers on the host system. FAT, NTFS, ext2, ext3, and ext4 + file systems are supported. + </para> + + <para> + Use the <option>--help</option> option to view information about + the <command>vboximg-mount</command> command usage. The complete + command reference is described in + <xref linkend="man_vboximg-mount" />. + </para> + + <para> + When <command>vboximg-mount</command> mounts an &product-name; + disk image, it creates a one level deep file system at a mount + point that you specify. The file system includes a device node + that represents the synthesized disk image as a readable or + readable-writeable bytestream. This bytestream can be mounted + either by using the host OS or by using other FUSE-based file + systems. + </para> + + <sect2 id="vboximg-mount-display"> + + <title>Viewing Detailed Information About a Virtual Disk Image</title> + + <para> + The following examples show how to use the + <command>vboximg-mount</command> command to view information + about virtual disk images. + </para> + + <para> + The following command outputs detailed information about all + registered VMs and associated snapshots: + </para> + +<screen>$ vboximg-mount --list --verbose + + ------------------------------------------------------ + VM Name: "macOS High Sierra 10.13" + UUID: 3887d96d-831c-4187-a55a-567c504ff0e1 + Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/macOS High Sierra 10.13.vbox + ----------------------- + HDD base: "macOS High Sierra 10.13.vdi" + UUID: f9ea7173-6869-4aa9-b487-68023a655980 + Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/macOS High Sierra 10.13.vdi + + Diff 1: + UUID: 98c2bac9-cf37-443d-a935-4e879b70166d + Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/ + Snapshots/{98c2bac9-cf37-443d-a935-4e879b70166d}.vdi + Diff 2: + UUID: f401f381-7377-40b3-948e-3c61241b1a42 + Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/ + Snapshots/{f401f381-7377-40b3-948e-3c61241b1a42}.vdi + ----------------------- + HDD base: "simple_fixed_disk.vdi" + UUID: ffba4d7e-1277-489d-8173-22ca7660773d + Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/simple_fixed_disk.vdi + + Diff 1: + UUID: aecab681-0d2d-468b-8682-93f79dc97a48 + Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/ + Snapshots/{aecab681-0d2d-468b-8682-93f79dc97a48}.vdi + Diff 2: + UUID: 70d6b34d-8422-47fa-8521-3b6929a1971c + Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/ + Snapshots/{70d6b34d-8422-47fa-8521-3b6929a1971c}.vdi + ------------------------------------------------------ + VM Name: "debian" + UUID: 5365ab5f-470d-44c0-9863-dad532ee5905 + Location: /Volumes/work/vm_guests/debian/debian.vbox + ----------------------- + HDD base: "debian.vdi" + UUID: 96d2e92e-0d4e-46ab-a0f1-008fdbf997e7 + Location: /Volumes/work/vm_guests/debian/ol7.vdi + + Diff 1: + UUID: f9cc866a-9166-42e9-a503-bbfe9b7312e8 + Location: /Volumes/work/vm_guests/debian/Snapshots/ + {f9cc866a-9166-42e9-a503-bbfe9b7312e8}.vdi</screen> + + <para> + The following command outputs partition information about the + specified disk image: + </para> + +<screen>$ vboximg-mount --image=f9ea7173-6869-4aa9-b487-68023a655980 --list + + Virtual disk image: + + Path: /Volumes/work/vm_guests/macOS High Sierra 10.13/macOS High Sierra 10.13.vdi + UUID: f9ea7173-6869-4aa9-b487-68023a655980 + + # Start Sectors Size Offset Type + 1 40 409599 199.9M 20480 EFI System + 2 409640 67453071 32.1G 209735680 Hierarchical File System Plus (HFS+) + 3 67862712 1269535 107.8M 34745708544 Apple Boot (Recovery HD)</screen> + + </sect2> + + <sect2 id="vboximg-mount-steps"> + + <title>Mounting a Virtual Disk Image</title> + + <para> + The following steps show how to use the + <command>vboximg-mount</command> command to mount a partition of + a virtual disk image on the host OS. + </para> + + <orderedlist> + + <listitem> + <para> + Create a mount point on the host OS. For example: + </para> + +<screen>$ mkdir macos_sysdisk</screen> + </listitem> + + <listitem> + <para> + Show partition information about the virtual disk image. + </para> + +<screen>$ vboximg-mount --image=<replaceable>uuid</replaceable> --list</screen> + + <para> + where <replaceable>uuid</replaceable> is the UUID of the + disk image. + </para> + </listitem> + + <listitem> + <para> + Use <command>vboximg-mount</command> to perform a FUSE mount + of a partition on the virtual disk image. For example: + </para> + +<screen>$ vboximg-mount --image=<replaceable>uuid</replaceable> -p 2 macos_sysdisk</screen> + + <para> + where <replaceable>uuid</replaceable> is the UUID for the + disk image. + </para> + + <para> + In this example, partition 2 is mounted on the + <filename>macos_sysdisk</filename> mount point. The mount + includes all snapshots for the disk image. + </para> + </listitem> + + <listitem> + <para> + Use the host OS to mount the <literal>vhdd</literal> device + node. The FUSE-mounted device node represents the virtual + disk image. + </para> + +<screen>$ ls macos_sysdisk + macOS High Sierra 10.13.vdi vhdd +$ sudo mount macos_sysdisk/vhdd /mnt</screen> + </listitem> + + </orderedlist> + + </sect2> + + </sect1> + +</chapter> diff --git a/doc/manual/en_US/user_Technical.xml b/doc/manual/en_US/user_Technical.xml new file mode 100644 index 00000000..7469c9e7 --- /dev/null +++ b/doc/manual/en_US/user_Technical.xml @@ -0,0 +1,962 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="TechnicalBackground"> + + <title>Technical Background</title> + + <para> + This chapter provides additional information for readers who are + familiar with computer architecture and technology and wish to find + out more about how &product-name; works <emphasis>under the + hood</emphasis>. The contents of this chapter are not required + reading in order to use &product-name; successfully. + </para> + + <sect1 id="vboxconfigdata"> + + <title>Where &product-name; Stores its Files</title> + + <para> + In &product-name;, a virtual machine and its settings are + described in a virtual machine settings file in XML format. In + addition, most virtual machines have one or more virtual hard + disks. These are typically represented by disk images, such as + those in VDI format. The location of these files may vary, + depending on the host operating system. See + <xref linkend="vboxconfigdata-machine-folder"/>. + </para> + + <para> + Global configuration data for &product-name; is maintained in + another location on the host. See + <xref linkend="vboxconfigdata-global"/>. + </para> + + <sect2 id="vboxconfigdata-machine-folder"> + + <title>The Machine Folder</title> + + <para> + By default, each virtual machine has a directory on your host + computer where all the files of that machine are stored: the XML + settings file, with a <filename>.vbox</filename> file extension, + and its disk images. This is called the <emphasis>machine + folder</emphasis>. + </para> + + <para> + By default, this machine folder is located in a common folder + called <filename>VirtualBox VMs</filename>, which &product-name; + creates in the current system user's home directory. The + location of this home directory depends on the conventions of + the host operating system, as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + On Windows, this is the location returned by the + <literal>SHGetFolderPath</literal> function of the Windows + system library Shell32.dll, asking for the user profile. A + typical location is + <filename>C:\Users\<replaceable>username</replaceable></filename>. + </para> + </listitem> + + <listitem> + <para> + On Linux, macOS, and Oracle Solaris, this is generally + taken from the environment variable + <filename>$HOME</filename>, except for the user + <literal>root</literal> where it is taken from the account + database. This is a workaround for the frequent trouble + caused by users using &product-name; in combination with the + tool <command>sudo</command>, which by default does not + reset the environment variable <filename>$HOME</filename>. + </para> + + <para> + A typical location on Linux and Oracle Solaris is + <filename>/home/<replaceable>username</replaceable></filename> + and on macOS is + <filename>/Users/<replaceable>username</replaceable></filename>. + </para> + </listitem> + + </itemizedlist> + + <para> + For simplicity, we abbreviate the location of the home directory + as <filename>$HOME</filename>. Using that convention, the common + folder for all virtual machines is <filename>$HOME/VirtualBox + VMs</filename>. + </para> + + <para> + As an example, when you create a virtual machine called "Example + VM", &product-name; creates the following: + </para> + + <itemizedlist> + + <listitem> + <para> + A machine folder: <filename>$HOME/VirtualBox VMs/Example + VM/</filename> + </para> + </listitem> + + <listitem> + <para> + In the machine folder, a settings file: <filename>Example + VM.vbox</filename> + </para> + </listitem> + + <listitem> + <para> + In the machine folder, a virtual disk image: + <filename>Example VM.vdi</filename>. + </para> + </listitem> + + </itemizedlist> + + <para> + This is the default layout if you use the + <emphasis role="bold">Create New Virtual Machine</emphasis> + wizard described in <xref linkend="create-vm-wizard" />. Once you + start working with the VM, additional files are added. Log files + are in a subfolder called <filename>Logs</filename>, and if you + have taken snapshots, they are in a + <filename>Snapshots</filename> subfolder. For each VM, you can + change the location of its snapshots folder in the VM settings. + </para> + + <para> + You can change the default machine folder by selecting + <emphasis role="bold">Preferences</emphasis> from the + <emphasis role="bold">File</emphasis> menu in the &product-name; + main window. Then, in the displayed window, click on the + <emphasis role="bold">General</emphasis> tab. Alternatively, use + the <command>VBoxManage setproperty machinefolder</command> + command. See <xref linkend="vboxmanage-setproperty" />. + </para> + + </sect2> + + <sect2 id="vboxconfigdata-global"> + + <title>Global Settings</title> + + <para> + In addition to the files for the virtual machines, + &product-name; maintains global configuration data in the + following directory: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Linux and Oracle Solaris:</emphasis> + <filename>$HOME/.config/VirtualBox</filename>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Windows:</emphasis> + <filename>$HOME/.VirtualBox</filename>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">macOS:</emphasis> + <filename>$HOME/Library/VirtualBox</filename>. + </para> + </listitem> + + </itemizedlist> + + <para> + &product-name; creates this configuration directory + automatically, if necessary. You can specify an alternate + configuration directory by either setting the + <literal>VBOX_USER_HOME</literal> environment variable, or on + Linux or Oracle Solaris by using the standard + <literal>XDG_CONFIG_HOME</literal> variable. Since the global + <filename>VirtualBox.xml</filename> settings file points to all + other configuration files, this enables switching between + several &product-name; configurations. + </para> + + <para> + In this configuration directory, &product-name; stores its + global settings file, an XML file called + <filename>VirtualBox.xml</filename>. This file includes global + configuration options and a list of registered virtual machines + with pointers to their XML settings files. + </para> + + </sect2> + + <sect2 id="vboxconfigdata-summary-locations"> + + <title>Summary of Configuration Data Locations</title> + + <para> + The following table gives a brief overview of the configuration + data locations on an &product-name; host. + </para> + + <table id="table-config-summary" tabstyle="oracle-all"> + <title>Configuration File Locations</title> + <tgroup cols="2"> + <thead> + <row> + <entry><para> + <emphasis role="bold">Setting</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Location</emphasis> + </para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para> + Default machines folder + </para></entry> + <entry><para> + <filename>$HOME/VirtualBox VMs</filename> + </para></entry> + </row> + <row> + <entry><para> + Default disk image location + </para></entry> + <entry><para> + In each machine's folder + </para></entry> + </row> + <row> + <entry><para> + Machine settings file extension + </para></entry> + <entry><para> + <filename>.vbox</filename> + </para></entry> + </row> + <row> + <entry><para> + Media registry + </para></entry> + <entry><para> + Each machine settings file + </para> + + + + <para> + Media registration is done automatically when a + storage medium is attached to a VM + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + </sect2> + + <sect2 id="vboxconfigdata-XML-files"> + + <title>&product-name; XML Files</title> + + <para> + &product-name; uses XML for both the machine settings files and + the global configuration file, + <filename>VirtualBox.xml</filename>. + </para> + + <para> + All &product-name; XML files are versioned. When a new settings + file is created, for example because a new virtual machine is + created, &product-name; automatically uses the settings format + of the current &product-name; version. These files may not be + readable if you downgrade to an earlier version of + &product-name;. However, when &product-name; encounters a + settings file from an earlier version, such as after upgrading + &product-name;, it attempts to preserve the settings format as + much as possible. It will only silently upgrade the settings + format if the current settings cannot be expressed in the old + format, for example because you enabled a feature that was not + present in an earlier version of &product-name;. + </para> + + <para> + In such cases, &product-name; backs up the old settings file in + the virtual machine's configuration directory. If you need to go + back to the earlier version of &product-name;, then you will + need to manually copy these backup files back. + </para> + + <para> + We intentionally do not document the specifications of the + &product-name; XML files, as we must reserve the right to modify + them in the future. We therefore strongly suggest that you do + not edit these files manually. &product-name; provides complete + access to its configuration data through its the + <command>VBoxManage</command> command line tool, see + <xref linkend="vboxmanage" /> and its API, see + <xref linkend="VirtualBoxAPI" />. + </para> + + </sect2> + + </sect1> + + <sect1 id="technical-components"> + + <title>&product-name; Executables and Components</title> + + <para> + &product-name; was designed to be modular and flexible. When the + &product-name; graphical user interface (GUI) is opened and a VM + is started, at least the following three processes are running: + </para> + + <itemizedlist> + + <listitem> + <para> + <command>VBoxSVC</command>, the &product-name; service process + which always runs in the background. This process is started + automatically by the first &product-name; client process and + exits a short time after the last client exits. The first + &product-name; service can be &vbox-mgr;, + <command>VBoxManage</command>, + <command>VBoxHeadless</command>, the web service amongst + others. The service is responsible for bookkeeping, + maintaining the state of all VMs, and for providing + communication between &product-name; components. This + communication is implemented using COM/XPCOM. + </para> + + <note> + <para> + When we refer to <emphasis>clients</emphasis> here, we mean + the local clients of a particular <command>VBoxSVC</command> + server process, not clients in a network. &product-name; + employs its own client/server design to allow its processes + to cooperate, but all these processes run under the same + user account on the host operating system, and this is + totally transparent to the user. + </para> + </note> + </listitem> + + <listitem> + <para> + The GUI process, <command>VirtualBoxVM</command>, a client + application based on the cross-platform Qt library. When + started without the <option>--startvm</option> option, this + application acts as &vbox-mgr;, displaying the VMs and their + settings. It then communicates settings and state changes to + <command>VBoxSVC</command> and also reflects changes effected + through other means, such as the <command>VBoxManage</command> + command. + </para> + </listitem> + + <listitem> + <para> + If the <command>VirtualBoxVM</command> client application is + started with the <option>--startvm</option> argument, it loads + the VMM library which includes the actual hypervisor and then + runs a virtual machine and provides the input and output for + the guest. + </para> + </listitem> + + </itemizedlist> + + <para> + Any &product-name; front-end, or client, will communicate with the + service process and can both control and reflect the current + state. For example, either the VM selector or the VM window or + VBoxManage can be used to pause the running VM, and other + components will always reflect the changed state. + </para> + + <para> + The &product-name; GUI application, called &vbox-mgr;, is only one + of several available front ends, or clients. The complete list + shipped with &product-name; is as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <command>VirtualBoxVM</command>: The Qt front end implementing + &vbox-mgr; and running VMs. + </para> + </listitem> + + <listitem> + <para> + <command>VBoxManage</command>: A less user-friendly but more + powerful alternative. See <xref linkend="vboxmanage" />. + </para> + </listitem> + + <listitem> + <para> + <command>VBoxHeadless</command>: A VM front end which does not + directly provide any video output and keyboard or mouse input, + but enables redirection through the VirtualBox Remote Desktop + Extension. See <xref linkend="vboxheadless" />. + </para> + </listitem> + + <listitem> + <para> + <command>vboxwebsrv</command>: The &product-name; web service + process which enables control of an &product-name; host + remotely. This is described in detail in the &product-name; + Software Development Kit (SDK) reference. See + <xref linkend="VirtualBoxAPI" />. + </para> + </listitem> + + <listitem> + <para> + The &product-name; Python shell: A Python alternative to + <command>VBoxManage</command>. This is also described in the + SDK reference. + </para> + </listitem> + + </itemizedlist> + + <para> + Internally, &product-name; consists of many more or less separate + components. You may encounter these when analyzing &product-name; + internal error messages or log files. These include the following: + </para> + + <itemizedlist> + + <listitem> + <para> + IPRT: A portable runtime library which abstracts file access, + threading, and string manipulation. Whenever &product-name; + accesses host operating features, it does so through this + library for cross-platform portability. + </para> + </listitem> + + <listitem> + <para> + VMM (Virtual Machine Monitor): The heart of the hypervisor. + </para> + </listitem> + + <listitem> + <para> + EM (Execution Manager): Controls execution of guest code. + </para> + </listitem> + + <listitem> + <para> + TRPM (Trap Manager): Intercepts and processes guest traps and + exceptions. + </para> + </listitem> + + <listitem> + <para> + HM (Hardware Acceleration Manager): Provides support for VT-x + and AMD-V. + </para> + </listitem> + + <listitem> + <para> + GIM (Guest Interface Manager): Provides support for various + paravirtualization interfaces to the guest. + </para> + </listitem> + + <listitem> + <para> + PDM (Pluggable Device Manager): An abstract interface between + the VMM and emulated devices which separates device + implementations from VMM internals and makes it easy to add + new emulated devices. Through PDM, third-party developers can + add new virtual devices to &product-name; without having to + change &product-name; itself. + </para> + </listitem> + + <listitem> + <para> + PGM (Page Manager): A component that controls guest paging. + </para> + </listitem> + + <listitem> + <para> + TM (Time Manager): Handles timers and all aspects of time + inside guests. + </para> + </listitem> + + <listitem> + <para> + CFGM (Configuration Manager): Provides a tree structure which + holds configuration settings for the VM and all emulated + devices. + </para> + </listitem> + + <listitem> + <para> + SSM (Saved State Manager): Saves and loads VM state. + </para> + </listitem> + + <listitem> + <para> + VUSB (Virtual USB): A USB layer which separates emulated USB + controllers from the controllers on the host and from USB + devices. This component also enables remote USB. + </para> + </listitem> + + <listitem> + <para> + DBGF (Debug Facility): A built-in VM debugger. + </para> + </listitem> + + <listitem> + <para> + &product-name; emulates a number of devices to provide the + hardware environment that various guests need. Most of these + are standard devices found in many PC compatible machines and + widely supported by guest operating systems. For network and + storage devices in particular, there are several options for + the emulated devices to access the underlying hardware. These + devices are managed by PDM. + </para> + </listitem> + + <listitem> + <para> + Guest Additions for various guest operating systems. This is + code that is installed from within a virtual machine. See + <xref linkend="guestadditions" />. + </para> + </listitem> + + <listitem> + <para> + The "Main" component is special. It ties all the above bits + together and is the only public API that &product-name; + provides. All the client processes listed above use only this + API and never access the hypervisor components directly. As a + result, third-party applications that use the &product-name; + Main API can rely on the fact that it is always well-tested + and that all capabilities of &product-name; are fully exposed. + It is this API that is described in the &product-name; SDK. + See <xref linkend="VirtualBoxAPI" />. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="hwvirt"> + + <title>Hardware Virtualization</title> + + <para> + &product-name; enables software in the virtual machine to run + directly on the processor of the host, but an array of complex + techniques is employed to intercept operations that would + interfere with your host. Whenever the guest attempts to do + something that could be harmful to your computer and its data, + &product-name; steps in and takes action. In particular, for lots + of hardware that the guest believes to be accessing, + &product-name; simulates a certain <emphasis>virtual</emphasis> + environment according to how you have configured a virtual + machine. For example, when the guest attempts to access a hard + disk, &product-name; redirects these requests to whatever you have + configured to be the virtual machine's virtual hard disk. This is + normally an image file on your host. + </para> + + <para> + Unfortunately, the x86 platform was never designed to be + virtualized. Detecting situations in which &product-name; needs to + take control over the guest code that is executing, as described + above, is difficult. To achieve this, &product-name; uses + <emphasis>hardware virtualization</emphasis>. + </para> + + <para> + Intel and AMD processors have support for hardware virtualization. + This means that these processors can help &product-name; to + intercept potentially dangerous operations that a guest operating + system may be attempting and also makes it easier to present + virtual hardware to a virtual machine. + </para> + + <para> + These hardware features differ between Intel and AMD processors. + Intel named its technology VT-x, AMD calls theirs AMD-V. The Intel + and AMD support for virtualization is very different in detail, + but not very different in principle. + </para> + + <note> + <para> + On many systems, the hardware virtualization features first need + to be enabled in the BIOS before &product-name; can use them. + </para> + </note> + + <para> + Enabling hardware virtualization is <emphasis>required</emphasis> + in the following scenarios: + </para> + + <itemizedlist> + + <listitem> + <para> + Certain rare guest operating systems like OS/2 make use of + very esoteric processor instructions. For virtual machines + that are configured to use such an operating system, hardware + virtualization is enabled automatically. + </para> + </listitem> + + <listitem> + <para> + &product-name;'s 64-bit guest and multiprocessing (SMP) + support both require hardware virtualization to be enabled. + This is not much of a limitation since the vast majority of + 64-bit and multicore CPUs ship with hardware virtualization. + The exceptions to this rule are some legacy Intel and AMD + CPUs. + </para> + </listitem> + + </itemizedlist> + + <warning> + <para> + Do not run other hypervisors, either open source or commercial + virtualization products, together with &product-name;. While + several hypervisors can normally be + <emphasis>installed</emphasis> in parallel, do not attempt to + <emphasis>run</emphasis> several virtual machines from competing + hypervisors at the same time. &product-name; cannot track what + another hypervisor is currently attempting to do on the same + host, and especially if several products attempt to use hardware + virtualization features such as VT-x, this can crash the entire + host. + </para> + </warning> + + <para> + See <xref linkend="hwvirt-details"/> for a technical discussion of + hardware virtualization. + </para> + + </sect1> + + <sect1 id="hwvirt-details"> + + <title>Details About Hardware Virtualization</title> + + <para> + With Intel VT-x, there are two distinct modes of CPU operation: + VMX root mode and non-root mode. + </para> + + <itemizedlist> + + <listitem> + <para> + In root mode, the CPU operates much like older generations of + processors without VT-x support. There are four privilege + levels, called rings, and the same instruction set is + supported, with the addition of several virtualization + specific instruction. Root mode is what a host operating + system without virtualization uses, and it is also used by a + hypervisor when virtualization is active. + </para> + </listitem> + + <listitem> + <para> + In non-root mode, CPU operation is significantly different. + There are still four privilege rings and the same instruction + set, but a new structure called VMCS (Virtual Machine Control + Structure) now controls the CPU operation and determines how + certain instructions behave. Non-root mode is where guest + systems run. + </para> + </listitem> + + </itemizedlist> + + <para> + Switching from root mode to non-root mode is called "VM entry", + the switch back is "VM exit". The VMCS includes a guest and host + state area which is saved/restored at VM entry and exit. Most + importantly, the VMCS controls which guest operations will cause + VM exits. + </para> + + <para> + The VMCS provides fairly fine-grained control over what the guests + can and cannot do. For example, a hypervisor can allow a guest to + write certain bits in shadowed control registers, but not others. + This enables efficient virtualization in cases where guests can be + allowed to write control bits without disrupting the hypervisor, + while preventing them from altering control bits over which the + hypervisor needs to retain full control. The VMCS also provides + control over interrupt delivery and exceptions. + </para> + + <para> + Whenever an instruction or event causes a VM exit, the VMCS + contains information about the exit reason, often with + accompanying detail. For example, if a write to the CR0 register + causes an exit, the offending instruction is recorded, along with + the fact that a write access to a control register caused the + exit, and information about source and destination register. Thus + the hypervisor can efficiently handle the condition without + needing advanced techniques such as CSAM and PATM described above. + </para> + + <para> + VT-x inherently avoids several of the problems which software + virtualization faces. The guest has its own completely separate + address space not shared with the hypervisor, which eliminates + potential clashes. Additionally, guest OS kernel code runs at + privilege ring 0 in VMX non-root mode, obviating the problems by + running ring 0 code at less privileged levels. For example the + SYSENTER instruction can transition to ring 0 without causing + problems. Naturally, even at ring 0 in VMX non-root mode, any I/O + access by guest code still causes a VM exit, allowing for device + emulation. + </para> + + <para> + The biggest difference between VT-x and AMD-V is that AMD-V + provides a more complete virtualization environment. VT-x requires + the VMX non-root code to run with paging enabled, which precludes + hardware virtualization of real-mode code and non-paged + protected-mode software. This typically only includes firmware and + OS loaders, but nevertheless complicates VT-x hypervisor + implementation. AMD-V does not have this restriction. + </para> + + <para> + Of course hardware virtualization is not perfect. Compared to + software virtualization, the overhead of VM exits is relatively + high. This causes problems for devices whose emulation requires + high number of traps. One example is a VGA device in 16-color + mode, where not only every I/O port access but also every access + to the framebuffer memory must be trapped. + </para> + + </sect1> + + <sect1 id="gimproviders"> + + <title>Paravirtualization Providers</title> + + <para> + &product-name; enables the exposure of a paravirtualization + interface, to facilitate accurate and efficient execution of + software within a virtual machine. These interfaces require the + guest operating system to recognize their presence and make use of + them in order to leverage the benefits of communicating with the + &product-name; hypervisor. + </para> + + <para> + Most modern, mainstream guest operating systems, including Windows + and Linux, ship with support for one or more paravirtualization + interfaces. Hence, there is typically no need to install + additional software in the guest to take advantage of this + feature. + </para> + + <para> + Exposing a paravirtualization provider to the guest operating + system does not rely on the choice of host platforms. For example, + the <emphasis>Hyper-V</emphasis> paravirtualization provider can + be used for VMs to run on any host platform supported by + &product-name; and not just Windows. + </para> + + <para> + &product-name; provides the following interfaces: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Minimal</emphasis>: Announces the + presence of a virtualized environment. Additionally, reports + the TSC and APIC frequency to the guest operating system. This + provider is mandatory for running any Mac OS X guests. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">KVM</emphasis>: Presents a Linux KVM + hypervisor interface which is recognized by Linux kernels + version 2.6.25 or later. &product-name;'s implementation + currently supports paravirtualized clocks and SMP spinlocks. + This provider is recommended for Linux guests. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Hyper-V</emphasis>: Presents a Microsoft + Hyper-V hypervisor interface which is recognized by Windows 7 + and newer operating systems. &product-name;'s implementation + currently supports paravirtualized clocks, APIC frequency + reporting, guest debugging, guest crash reporting and relaxed + timer checks. This provider is recommended for Windows guests. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="nestedpaging"> + + <title>Nested Paging and VPIDs</title> + + <para> + In addition to normal hardware virtualization, your processor may + also support the following additional sophisticated techniques: + </para> + + <itemizedlist> + + <listitem> + <para> + Nested paging implements some memory management in hardware, + which can greatly accelerate hardware virtualization since + these tasks no longer need to be performed by the + virtualization software. + </para> + + <para> + With nested paging, the hardware provides another level of + indirection when translating linear to physical addresses. + Page tables function as before, but linear addresses are now + translated to "guest physical" addresses first and not + physical addresses directly. A new set of paging registers now + exists under the traditional paging mechanism and translates + from guest physical addresses to host physical addresses, + which are used to access memory. + </para> + + <para> + Nested paging eliminates the overhead caused by VM exits and + page table accesses. In essence, with nested page tables the + guest can handle paging without intervention from the + hypervisor. Nested paging thus significantly improves + virtualization performance. + </para> + + <para> + On AMD processors, nested paging has been available starting + with the Barcelona (K10) architecture. They now call it rapid + virtualization indexing (RVI). Intel added support for nested + paging, which they call extended page tables (EPT), with their + Core i7 (Nehalem) processors. + </para> + + <para> + If nested paging is enabled, the &product-name; hypervisor can + also use <emphasis>large pages</emphasis> to reduce TLB usage + and overhead. This can yield a performance improvement of up + to 5%. To enable this feature for a VM, you use the + <command>VBoxManage modifyvm --large-pages</command> command. + See <xref linkend="vboxmanage-modifyvm" />. + </para> + + <para> + If you have an Intel CPU with EPT, please consult + <xref linkend="sec-rec-cve-2018-3646" /> for security concerns + regarding EPT. + </para> + </listitem> + + <listitem> + <para> + On Intel CPUs, a hardware feature called Virtual Processor + Identifiers (VPIDs) can greatly accelerate context switching + by reducing the need for expensive flushing of the processor's + Translation Lookaside Buffers (TLBs). + </para> + + <para> + To enable these features for a VM, you use the + <command>VBoxManage modifyvm --vtx-vpid</command> and + <command>VBoxManage modifyvm --large-pages</command> commands. + See <xref linkend="vboxmanage-modifyvm" />. + </para> + </listitem> + + </itemizedlist> + + </sect1> + +</chapter> diff --git a/doc/manual/en_US/user_ThirdParty.xml b/doc/manual/en_US/user_ThirdParty.xml new file mode 100644 index 00000000..7d88c5a4 --- /dev/null +++ b/doc/manual/en_US/user_ThirdParty.xml @@ -0,0 +1,11811 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<appendix id="ThirdParty"> + + <title>Third-Party Materials and Licenses</title> + + <para> + &product-name; incorporates materials from several Open Source + software projects. Therefore the use of these materials by + &product-name; is governed by different Open Source licenses. This + document reproduces these licenses and provides a list of the + materials used and their respective licensing conditions. Section 1 + contains a list of the materials used. Section 2 reproduces the + applicable Open Source licenses. For each material, a reference to + its license is provided. + </para> + + <para> + The source code for the materials listed below as well as the rest + of the &product-name; code which is released as open source are + available at + <ulink url="http://www.virtualbox.org" />, + both as tarballs for particular releases and as a live SVN + repository. + </para> + + <sect1 id="third-party-materials"> + + <title>Third-Party Materials</title> + + <itemizedlist> + + <listitem> + <para> + &product-name; contains portions of QEMU which is governed by + the licenses in + <xref linkend="licX11" xrefstyle="template: %n" /> and + <xref linkend="licLGPL" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1998, 2003-2005 Fabrice Bellard; Copyright (C) + 2004 Magnus Damm; Copyright (C) 2003-2005 Vassili Karpov + (malc); Copyright (C) 2004 Antony T Curtis; Copyright (C) + 2003 Jocelyn Mayer + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X Window System which is + governed by the license in + <xref linkend="licX11" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 2004 by the Massachusetts Institute of Technology. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the BOCHS VGA BIOS which is + governed by the license in + <xref linkend="licLGPL" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 2001,2002 the LGPL VGABios developers Team. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the BOCHS ROM BIOS which is + governed by the license in + <xref linkend="licLGPL" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 2002 MandrakeSoft S.A. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains the zlib library which is governed by + the license in + <xref linkend="licZLIB" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1995-2022 Jean-loup Gailly and Mark Adler. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains OpenSSL 3.0 or later which is governed by the + license in <xref linkend="licApache" xrefstyle="template: %n" /> + and + </para> + + <para> + Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains OpenSSL before 3.0 which is governed by the + license in <xref linkend="licSSL" xrefstyle="template: %n" /> + and + </para> + + <para> + Copyright (C) 1998-2019 The OpenSSL Project. All rights reserved.; + Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com). This + product includes software written by Tim Hudson + (tjh@cryptsoft.com). + </para> + </listitem> + + <listitem> + <para> + &product-name; may contain NSPR and XPCOM which is governed by + the license in + <xref linkend="licMPL" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 2002-2003 Netscape Communications Corporation. + All Rights Reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains Slirp which is governed by the license + in <xref linkend="licSlirp" xrefstyle="template: %n" /> and + was written by Danny Gasparovski. + </para> + + <para> + Copyright (c) 1995,1996 Danny Gasparovski. All rights reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains liblzf which is governed by the + license in <xref linkend="licLZF" xrefstyle="template: %n" /> + and + </para> + + <para> + Copyright (C) 2000-2009 Marc Alexander Lehmann + <schmorp@schmorp.de> + </para> + </listitem> + + <listitem> + <para> + &product-name; may contain iPXE which is governed by the + license in <xref linkend="licGPL" xrefstyle="template: %n" /> + and + </para> + + <para> + Copyright (C) 2015 Michael Brown <mbrown@fensystems.co.uk> + and others. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from Wine which is governed by + the license in + <xref linkend="licLGPL" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 1993-2015 the Wine project authors + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from lwIP which is governed by + the license in + <xref linkend="licLWIP" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 2001, 2004 Swedish Institute of Computer + Science. All rights reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains libxml2 which is governed by the + license in + <xref linkend="licLibXML" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1998-2012 Daniel Veillard. All Rights Reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the gSOAP XML web services + tools, which are licensed under the license in + <xref + linkend="licgSOAP" xrefstyle="template: %n" /> + and + </para> + + <para> + Copyright (C) 2000-2022, Robert van Engelen, Genivia Inc., and + others. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains libcurl which is governed by the + license in + <xref linkend="licLibCurl" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1996-2022, Daniel Stenberg. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains dnsproxy which is governed by the + license in <xref linkend="licMIT" xrefstyle="template: %n" /> + and + </para> + + <para> + Copyright (c) 2003, 2004, 2005 Armin Wolfermann + </para> + </listitem> + + <listitem> + <para> + &product-name; contains some code from libgd which is governed + by the license in + <xref linkend="licLibgd" xrefstyle="template: %n"/> and + </para> + + <para> + Portions Copyright 2000, 2001, 2002, 2003, 2004, 2005, 2006, + 2007, 2008 Pierre-Alain Joye (pierre@libgd.org). For complete + copyright information, see the license. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the EFI Development Kit II + (EDK II) which is governed by the licenses in + <xref linkend="licBsdIntel" xrefstyle="template: %n" /> and + <xref linkend="licMIT" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2019, TianoCore and contributors.; + Copyright (c) 2004-2019, Intel Corporation.; + Copyright (c) 2011, Andrei Warkentin <andreiw@motorola.com>; + Copyright (c) 2011, Bei Guan <gbtju85@gmail.com>; + Copyright (c) 2012-2018, Red Hat, Inc.; + Copyright (c) 2014, Pluribus Networks, Inc.; + Copyright (c) 2015 Nahanni Systems + Copyright (c) 2016 Hewlett Packard Enterprise Development LP; + Copyright (c) 2017, Advanced Micro Devices. All rights reserved.; + Copyright (c) 2020, Rebecca Cran <rebecca@bsdio.com> + Portions copyright (c) 2010, 2011, Apple Inc. All rights reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains libjpeg-turbo which is governed by the + licenses in <xref linkend="licIJG" xrefstyle="template: %n" /> + and <xref linkend="licBsdJPEG" xrefstyle="template: %n" /> + and + </para> + + <para> + Copyright (C) 1991-2020, Thomas G. Lane, Guido Vollbeding. + Copyright (C)2009-2022 D. R. Commander. All Rights Reserved. + Copyright (C)2015 Viktor Szathmáry. All Rights Reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; may contain the libjpeg-turbo x86 SIMD extensions + which is governed by the license in + <xref linkend="licZLIB" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1995-2022 Jean-loup Gailly and Mark Adler. + </para> + </listitem> + + <listitem> + <para> + &product-name; may ship a copy of Qt which is governed by the + license in <xref linkend="licLGPL" xrefstyle="template: %n" /> + and + </para> + + <para> + Copyright (C) 2015 The Qt Company Ltd. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains parts of the FreeBSD kernel which is + governed by the license in + <xref linkend="licFreeBsd" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 1992-2022 The FreeBSD Project. + </para> + + </listitem> + + <listitem> + <para> + &product-name; contains parts of the NetBSD kernel which is + governed by the license in + <xref linkend="licNetBsd" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2008 The NetBSD Foundation, Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; may contain code from the WebM VP8 Codec SDK + which is governed by the license in + <xref linkend="licVPX" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2010, 2013, 2016, 2019 The WebM Project authors. + All rights reserved.; Copyright (C) 2002-2010 The Xiph.Org + Foundation and contributors.; Copyright (C) 2005-2016 x264 + project; Copyright (c) 2010, Google Inc. All rights reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; may contain code from libvorbis ("Vorbis") which is + governed by the license in + <xref linkend="licVorbis" xrefstyle="template: %n" /> and + </para> + <para> + Monty <monty@xiph.org> + + and the rest of the Xiph.org Foundation. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from cURL which is governed by the + license in + <xref linkend="licCurl" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 1996 - 2022, Daniel Stenberg, + <daniel@haxx.se>, and others. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains documentation generated using the + DocBook XML DTD which is governed by the license in + <xref linkend="licDocBook-XML-DTD" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 1992-2004 HaL Computer Systems, Inc., O'Reilly + & Associates, Inc., ArborText, Inc., Fujitsu Software + Associates, Inc., ArborText, Inc., Fujitsu Software + Corporation, Norman Walsh, Sun Microsystems, Inc., and the + Organization for the Advancement of Structured Information + Standards (OASIS). + </para> + </listitem> + + <listitem> + <para> + &product-name; contains documentation generated using + DocBook XSL Stylesheets which is governed by the license in + <xref linkend="licDocBook-XSL-SS" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1999, 2000, 2001, 2002 Norman Walsh + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the ACPI Component + Architecture (ACPICA) project which is governed by the license + in <xref linkend="licIntel" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 1999 - 2010, Intel Corp. All rights reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the Independent JPEG (IJG) + Group which is governed by the license in + <xref linkend="licIJG" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1991-2021, Thomas G. Lane, Guido Vollbeding. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the Linux kernel which is + governed by the license in + <xref linkend="licGPL" xrefstyle="template: %n" /> + </para> + </listitem> + + <listitem> + <para> + &product-name; contains makeself which is governed by the + license in + <xref linkend="licGPL" xrefstyle="template: %n" /> + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the Mesa 3D graphics library + which is governed by the default Mesa license in + <xref linkend="licMesa-default" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1999-2007 Brian Paul All Rights Reserved. + For complete copyright information, see the license. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the Microsoft Windows Driver + Kit (WDK) which is governed by the license in + <xref linkend="licMicrosoft" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1999-2007 Brian Paul All Rights Reserved. + For complete copyright information, see the license. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from MoltenVK which is governed by + the license in + <xref linkend="licApache" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2015-2022 The Brenwill Workshop Ltd. (http://www.brenwill.com) + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the NSIS AccessControl plugin + which is governed by the license in + <xref linkend="licZLIB" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1999-2009 Nullsoft and Contributors; Copyright + (C) 2003 Mathias Hasselmann <mathias@taschenorakel.de> + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the NSIS NsProcess plugin + which is governed by the license in + <xref linkend="licZLIB" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1999-2008 Nullsoft and Contributors + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the Khronos OpenGL Registry + which is governed by the license in + <xref linkend="licKhronos" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2008-2018 The Khronos Group Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from Python which is governed by + the license in + <xref linkend="licCPython" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2001-2022 Python Software Foundation. All rights + reserved.; Copyright (c) 2000 BeOpen.com. All rights + reserved.; Copyright (c) 1995-2001 Corporation for National + Research Initiatives. All rights reserved.; Copyright (c) + 1991-1995 Stichting Mathematisch Centrum. All rights reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the SPIR-V Registry which is + governed by the license in + <xref linkend="licKhronos" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2008-2018 The Khronos Group Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from SPIRV-Cross which is governed + by the license in + <xref linkend="licApache" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2014-2021 The Khronos Group, Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the SPIR-V Tools project + which is governed by the license in + <xref linkend="licApache" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2015-2020 The Khronos Group Inc.;Modifications + Copyright (C) 2020 Advanced Micro Devices, Inc. All rights + reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from Berkeley SoftFloat which is + governed by the license in + <xref linkend="licBSD-SoftFloat" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 The Regents of the + University of California. All rights reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the Vulkan Header files and + API registry which is governed by the license in + <xref linkend="licApache" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2015-2016 The Khronos Group Inc.; Copyright (c) + 2015-2016 Valve Corporation; Copyright (c) 2015-2016 LunarG, Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the Vulkan tools which is + governed by the license in + <xref linkend="licApache" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2015-2021 The Khronos Group Inc.; Copyright (c) + 2015-2021 Valve Corporation; Copyright (c) 2015-2021 LunarG, + Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from Glslang which is governed by + the licenses in + <xref linkend="licBSD-3Clause-Glslang" xrefstyle="template: %n" /> and + <xref linkend="licBSD-2Clause-Glslang" xrefstyle="template: %n" /> and + <xref linkend="licMIT" xrefstyle="template: %n" /> and + <xref linkend="licApache" xrefstyle="template: %n" /> and + <xref linkend="licGPL-Bison-Glslang" xrefstyle="template: %n" /> and + <xref linkend="licNVIDIA-Glslang" xrefstyle="template: %n" /> and + <xref linkend="licKhronos-Glslang" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1984, 1989-1990, 2000-2015, 2018-2020 Free + Software Foundation, Inc.; Copyright (C) 2002-2005 3Dlabs Inc. + Ltd.; Copyright (c) 2002-2010 The ANGLE Project Authors.; + Copyright (c) 2002, NVIDIA Corporation.; Copyright (C) + 2012-2021 LunarG, Inc.; Copyright (c) 2013-2021 The Khronos + Group Inc.; Copyright (c) 2015-2021 Google Inc.; Copyright (c) + 2015-2021 Valve Corporation; Copyright (C) 2017, 2019 ARM + Limited.; Copyright (c) 2019, Viktor Latypov; Copyright (C) + 2020-2021 Advanced Micro Devices, Inc. All rights; Copyright + (c) 2020, Travis Fort; Copyright 2017 The Glslang Authors. All + rights reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the EGL-Registry repository + which is governed by the licenses in + <xref linkend="licApache" xrefstyle="template: %n" /> and + <xref linkend="licKhronos-EGL" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2008-2020 The Khronos Group Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the Wayland project which is + governed by the license in + <xref linkend="licMIT" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2008-2012 Kristian Høgsberg; Copyright (c) + 2010-2012 Intel Corporation; Copyright (c) 2011 Benjamin + Franzke; Copyright (c) 2012 Collabora, Ltd. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the WiX toolset which is + governed by the license in + <xref linkend="licWix-Toolset" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2008-2012 Kristian Høgsberg; Copyright (c) + 2010-2012 Intel Corporation; Copyright (c) 2011 Benjamin + Franzke; Copyright (c) 2012 Collabora, Ltd. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the XFree86-VidModeExtension + which is governed by the license in + <xref linkend="licXFree86" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1994-2003 The XFree86 Project, Inc. All Rights + Reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the Advanced Linux Sound + Architecture (ALSA) project which is governed by the license + in <xref linkend="licLGPL" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 1994-2007, 2010 by Jaroslav Kysela + <perex@perex.cz>; Copyright (c) 1998-1999 by Frank van + de Pol <fvdpol@coil.demon.nl>; Copyright (c) 1999 by + Uros Bizjak <uros@kss-loka.si>; Copyright (c) 1994-2003 + by Abramo Bagnara <abramo@alsa-project.org>; Copyright + (c) 2016 by Thomas Klausner <wiz@NetBSD.org>; Copyright + (c) 2006-2007 Diego Pettenò <flameeyes@gmail.com>; + Copyright (c) 2014-2015 Intel Corporation; Copyright (C) 2010 + Red Hat Inc.; Copyright (C) 2000-2002 Richard W.E. Furse, Paul + Barton-Davis, Stefan Westerfeld; Copyright (C) 2008-2010 + SlimLogic Ltd; Copyright (C) 1998,99,2000, 2003-2007, 2015 + Takashi Iwai <tiwai@suse.de>; Copyright (c) 2015-2016 + Takashi Sakamoto; Copyright (C) 2010, 2012 Texas Instruments + Inc.; Copyright (C) 2003 Thomas Charbonnel + (thomas@undata.org); Copyright (C) 2003 Winfried Ritsch (IEM); + Copyright (C) 2010 Wolfson Microelectronics PLC; Copyright (C) + 1994 X Consortium; Copyright (c) 2006-2007 xine project + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the cereal C++11 + serialization library which is governed by the license in + <xref linkend="licCereal" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2013-2022, Randolph Voorhies, Shane Grant + All rights reserved.; (C) Copyright 2002 Robert Ramey - + http://www.rrsd.com; (C) Copyright 2006 David Abrahams - + http://www.boost.org.; Copyright (C) 2004-2008 René + Nyffenegger; Copyright (c) 2014, 2017, Juan Pedro; Copyright + (c) 2015, Kyle Fleming, Juan Pedro Bolivar Puente; Copyright + (c) 2017, Juan Pedro Bolivar Puente; Copyright (c) 2006-2013 + Alexander Chemeris; Copyright (C) 2006, 2007, 2009 Marcin + Kalicinski; Copyright (c) 2016-2021 Viktor Kirilov; Copyright + (C) 2015 THL A29 Limited, a Tencent company, and Milo Yip. All + rights reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X Composite Extension + which is governed by the licenses in + <xref linkend="licX11" xrefstyle="template: %n" /> and + <xref linkend="licX-KeithPackard1" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2006, Oracle and/or its affiliates. All rights + reserved.; Copyright (c) 2003 Keith Packard, Noah Levitt + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X Damage Extension which + is governed by the license in + <xref linkend="licX-KeithPackard1" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2001,2003 Keith Packard; Copyright (c) 2007 Eric Anholt + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X Direct Rendering + Infrastructure (DRI) 2 Extension which is governed by the + license in + <xref linkend="licX-DRI2" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2007 Red Hat, Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X Fixes Extension which + is governed by the licenses in + <xref linkend="licX11" xrefstyle="template: %n" /> and + <xref linkend="licX-KeithPackard1" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2006, Oracle and/or its affiliates. All rights + reserved.; Copyright 2010 Red Hat, Inc.; Copyright (c) + 2001,2003 Keith Packard + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X Fonts Extension which + is governed by the licenses in + <xref linkend="licX-NCD-DEC" xrefstyle="template: %n" /> and + <xref linkend="licMIT-OpenGroup" xrefstyle="template: %n" /> and + <xref linkend="licX-DEC1" xrefstyle="template: %n" /> and + <xref linkend="licXFree86" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 1990, 1991 Network Computing Devices; Portions + Copyright 1987 by Digital Equipment Corporation; Copyright + 1990, 1991, 1998 The Open Group; Copyright 1987 by Digital + Equipment Corporation, Maynard, Massachusetts.; Copyright (c) + 1999 The XFree86 Project Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X OpenGL Extension (GLX) + which is governed by the license in + <xref linkend="licSGI-FSL-B" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1991-2000 Silicon Graphics, Inc. All Rights + Reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X Input Extension which + is governed by the licenses in + <xref linkend="licMIT-OpenGroup" xrefstyle="template: %n" /> and + <xref linkend="licX-HP1" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 1989, 1998 The Open Group; Copyright 1989 by + Hewlett-Packard Company, Palo Alto, California. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X Keyboard Extension which + is governed by the license in + <xref linkend="licX-SGI" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 1993 by Silicon Graphics Computer Systems, Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X Resize and Rotate + Extension (RandR) Extension which is governed by the license + in + <xref linkend="licX-RandR" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2000 Compaq Computer Corporation; Copyright (c) + 2002 Hewlett-Packard Company; Copyright (c) 2006 Intel + Corporation; Copyright (c) 2008 Red Hat, Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X Rendering Extension which + is governed by the license in + <xref linkend="licX-SuSE" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2000 SuSE, Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X XExt Extension which + is governed by the licenses in + <xref linkend="licMIT-OpenGroup" xrefstyle="template: %n" /> and + <xref linkend="licX-SGI" xrefstyle="template: %n" /> and + <xref linkend="licX-NCD1" xrefstyle="template: %n" /> and + <xref linkend="licX-HP2" xrefstyle="template: %n" /> and + <xref linkend="licX-DEC2" xrefstyle="template: %n" /> and + <xref linkend="licX-NCD2" xrefstyle="template: %n" /> and + <xref linkend="licX-DEC-Olivetti" xrefstyle="template: %n" /> and + <xref linkend="licX-HP3" xrefstyle="template: %n" /> and + <xref linkend="licMIT" xrefstyle="template: %n" /> and + <xref linkend="licX11" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 1989, 1998 The Open Group; Copyright (c) 1997 by + Silicon Graphics Computer Systems, Inc.; Copyright 1992 + Network Computing Devices; Copyright (c) 1994, 1995 + Hewlett-Packard Company; Copyright (c) 1996 Digital Equipment + Corporation, Maynard, Massachusetts.; Copyright 1988, 1989, + 1990, 1994 Network Computing Devices, Inc.; Copyright + 1991,1993 by Digital Equipment Corporation, Maynard, + Massachusetts, and Olivetti Research Limited, Cambridge, + England.; Copyright 1986, 1987, 1988 by Hewlett-Packard + Corporation + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the XFree86 Direct Rendering + Infrastructure (DRI) Extension which is governed by the + license in + <xref linkend="licMIT" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 1998-1999 Precision Insight, Inc., Cedar Park, + Texas.; Copyright 2000 VA Linux Systems, Inc.; All Rights + Reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the libXcomposite library + which is governed by the licenses in + <xref linkend="licX-KeithPackard1" xrefstyle="template: %n" /> and + <xref linkend="licMIT" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2001,2003 Keith Packard; Copyright (c) 2006, 2007, + Oracle and/or its affiliates. All rights reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the libXdamage library + which is governed by the licenses in + <xref linkend="licX-KeithPackard1" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2001,2003 Keith Packard; Copyright (c) 2007 Eric Anholt + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the libXext library + which is governed by the licenses in + <xref linkend="licMIT-OpenGroup" xrefstyle="template: %n" /> and + <xref linkend="licX-SGI" xrefstyle="template: %n" /> and + <xref linkend="licX-NCD1" xrefstyle="template: %n" /> and + <xref linkend="licX-HP2" xrefstyle="template: %n" /> and + <xref linkend="licX-DEC2" xrefstyle="template: %n" /> and + <xref linkend="licX-DEC-Olivetti" xrefstyle="template: %n" /> and + <xref linkend="licX-HP3" xrefstyle="template: %n" /> and + <xref linkend="licMIT" xrefstyle="template: %n" /> and + <xref linkend="licX11-Multi-party" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 1986, 1987, 1988, 1989, 1994, 1998 The Open Group; + Copyright (c) 1996 Digital Equipment Corporation, Maynard, + Massachusetts.; Copyright (c) 1997 by Silicon Graphics + Computer Systems, Inc.; Copyright 1992 Network Computing + Devices; Copyright 1991,1993 by Digital Equipment Corporation, + Maynard, Massachusetts, and Olivetti Research Limited, + Cambridge, England.; Copyright 1986, 1987, 1988 by + Hewlett-Packard Corporation; Copyright (c) 1994, 1995 + Hewlett-Packard Company; Copyright Digital Equipment + Corporation, 1996; Copyright (c) 1999, 2005, 2006, 2013, + Oracle and/or its affiliates.; Copyright (c) 1989 X + Consortium, Inc. and Digital Equipment Corporation.; Copyright + (c) 1992 X Consortium, Inc. and Intergraph Corporation.; + Copyright (c) 1993 X Consortium, Inc. and Silicon Graphics, + Inc.; Copyright (c) 1994, 1995 X Consortium, Inc. and + Hewlett-Packard Company. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the libXfixes library which + is governed by the license in + <xref linkend="licX-KeithPackard1" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2001,2003 Keith Packard + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X libpciaccess library + which is governed by the licenses in + <xref linkend="licMIT" xrefstyle="template: %n" /> and + <xref linkend="licX-Sun" xrefstyle="template: %n" /> and + <xref linkend="licX-Pardines-Kettenis" xrefstyle="template: %n" /> and + <xref linkend="licXFree86" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 2007 Free Software Foundation, Inc.; (C) + Copyright Eric Anholt 2006; (C) Copyright IBM Corporation + 2006; Copyright (C) 2008 Free Software Foundation, Inc.; + Copyright 2005 Red Hat, Inc; Copyright (c) 2008 Juan Romero + Pardines; Copyright (c) 2008 Mark Kettenis; Copyright (c) 2007 + Paulo R. Zanoni, Tiago Vignatti; Copyright 2005-2009 Sun + Microsystems, Inc. All rights reserved.; Copyright (C) 2000 + The XFree86 Project, Inc. All Rights Reserved.; Copyright (c) + 2009 Tiago Vignatti + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the libxshmfence library which + is governed by the license in + <xref linkend="licX-libxshmfence" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2013 Keith Packard; Copyright (c) 2013 Jung-uk + Kim <jkim@FreeBSD.org> + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the pixman library which + is governed by the license in + <xref linkend="licMIT" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 1987, 1988, 1989, 1998 The Open Group; Copyright + 1987, 1988, 1989 Digital Equipment Corporation; Copyright + 1999, 2004, 2008 Keith Packard; Copyright 2000 SuSE, Inc.; + Copyright 2000 Keith Packard, member of The XFree86 Project, + Inc.; Copyright 2004, 2005, 2007, 2008, 2009, 2010 Red Hat, + Inc.; Copyright 2004 Nicholas Miell; Copyright 2005 Lars Knoll + & Zack Rusin, Trolltech; Copyright 2005 Trolltech AS; + Copyright 2007 Luca Barbato; Copyright 2008 Aaron Plattner, + NVIDIA Corporation; Copyright 2008 Rodrigo Kumpera; Copyright + 2008 André Tupinambá; Copyright 2008 Mozilla Corporation; + Copyright 2008 Frederic Plourde; Copyright 2009, Oracle and/or + its affiliates. All rights reserved.; Copyright 2009, 2010 + Nokia Corporation + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the xf86-input-mouse driver + which is governed by the licenses in + <xref linkend="licX-Mouse" xrefstyle="template: %n" /> and + <xref linkend="licX-Yokota" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 1997-1999 by The XFree86 Project, Inc.; + Copyright 1990,91 by Thomas Roell, Dinkelscherben, Germany.; + Copyright 1993 by David Dawes <dawes@xfree86.org>; + Copyright 1994-2002 by The XFree86 Project, Inc.; Copyright + 1998 by Kazutaka YOKOTA + <yokota@zodiac.mech.utsunomiya-u.ac.jp>; Copyright 2002 + by Paul Elliott; Copyright 2002 by SuSE Linux AG, Author: + Egbert Eich; Copyright 2005 Red Hat, Inc; Copyright 2005 Sun + Microsystems, Inc. All rights reserved.; Copyright 2005 Adam + Jackson + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the xf86-video-vesa driver + which is governed by the license in + <xref linkend="licX-Connectiva" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2000 by Conectiva S.A. + (http://www.conectiva.com); Authors: Paulo César Pereira de + Andrade <pcpa@conectiva.com.br> David Dawes + <dawes@xfree86.org> + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the Xorg X server which is + governed by the licenses in + <xref linkend="licMIT" xrefstyle="template: %n" /> and + <xref linkend="licXFree86" xrefstyle="template: %n" /> and + <xref linkend="licXFree86-v2" xrefstyle="template: %n" /> and + <xref linkend="licMIT-OpenGroup" xrefstyle="template: %n" /> and + <xref linkend="licX-SuSE" xrefstyle="template: %n" /> and + <xref linkend="licX-DEC1" xrefstyle="template: %n" /> and + <xref linkend="licX-DEC-Quarterdeck" xrefstyle="template: %n" /> and + <xref linkend="licX-DEC3" xrefstyle="template: %n" /> and + <xref linkend="licX-DEC2" xrefstyle="template: %n" /> and + <xref linkend="licSGI-FSL-B" xrefstyle="template: %n" /> and + <xref linkend="licX-HP2" xrefstyle="template: %n" /> and + <xref linkend="licX-HP1" xrefstyle="template: %n" /> and + <xref linkend="licX-RedHat-SuSE" xrefstyle="template: %n" /> and + <xref linkend="licX-RedHat" xrefstyle="template: %n" /> and + <xref linkend="licX11-RedHat" xrefstyle="template: %n" /> and + <xref linkend="licX-PrecisionInsight" xrefstyle="template: %n" /> and + <xref linkend="licX-VALinux-IBM" xrefstyle="template: %n" /> and + <xref linkend="licX-IBM" xrefstyle="template: %n" /> and + <xref linkend="licX-MetroLink1" xrefstyle="template: %n" /> and + <xref linkend="licX-MetroLink2" xrefstyle="template: %n" /> and + <xref linkend="licX-MetroLink3" xrefstyle="template: %n" /> and + <xref linkend="licX-Connectiva" xrefstyle="template: %n" /> and + <xref linkend="licX-NVIDIA" xrefstyle="template: %n" /> and + <xref linkend="licX-Vrije" xrefstyle="template: %n" /> and + <xref linkend="licX-Concurrent" xrefstyle="template: %n" /> and + <xref linkend="licX-Nokia" xrefstyle="template: %n" /> and + <xref linkend="licX-Adobe" xrefstyle="template: %n" /> and + <xref linkend="licX-NCD3" xrefstyle="template: %n" /> and + <xref linkend="licX-UC" xrefstyle="template: %n" /> and + <xref linkend="licX-OMRON-DG" xrefstyle="template: %n" /> and + <xref linkend="licX-KeithPackard1" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy1" xrefstyle="template: %n" /> and + <xref linkend="licX-DavorMatic" xrefstyle="template: %n" /> and + <xref linkend="licX-HaroldHuntII" xrefstyle="template: %n" /> and + <xref linkend="licX-Roell" xrefstyle="template: %n" /> and + <xref linkend="licX-Roell-Wexelblat" xrefstyle="template: %n" /> and + <xref linkend="licX-Roell-SGCS" xrefstyle="template: %n" /> and + <xref linkend="licX-Hourihane" xrefstyle="template: %n" /> and + <xref linkend="licX-Keithley" xrefstyle="template: %n" /> and + <xref linkend="licX-Herrb" xrefstyle="template: %n" /> and + <xref linkend="licX-Eich" xrefstyle="template: %n" /> and + <xref linkend="licX-Wexelblat" xrefstyle="template: %n" /> and + <xref linkend="licX-Zborowski-Wexelblat" xrefstyle="template: %n" /> and + <xref linkend="licX-Zborowski-Dawes" xrefstyle="template: %n" /> and + <xref linkend="licX-Lepied" xrefstyle="template: %n" /> and + <xref linkend="licX-Murphy-Wexelblat" xrefstyle="template: %n" /> and + <xref linkend="licX-Murphey-Dawes" xrefstyle="template: %n" /> and + <xref linkend="licX-Carlsson" xrefstyle="template: %n" /> and + <xref linkend="licX-Anholt" xrefstyle="template: %n" /> and + <xref linkend="licX-Miller" xrefstyle="template: %n" /> and + <xref linkend="licX-Blundell" xrefstyle="template: %n" /> and + <xref linkend="licXFree86" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy2" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy3" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy4" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy5" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy6" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy7" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy8" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy9" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy11" xrefstyle="template: %n" /> and + <xref linkend="licX-AureleLF" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy12" xrefstyle="template: %n" /> and + <xref linkend="licX-Johnston" xrefstyle="template: %n" /> and + <xref linkend="licX-Jelinek" xrefstyle="template: %n" /> and + <xref linkend="licX-Yasushi" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy13" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy14" xrefstyle="template: %n" /> and + <xref linkend="licX-OpenedHand" xrefstyle="template: %n" /> and + <xref linkend="licX-UC2" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2000-2001 Juliusz Chroboczek; Copyright (c) 1998 + Egbert Eich; Copyright (c) 2006-2007 Intel Corporation; + Copyright (c) 2006 Nokia Corporation; Copyright (c) 2006-2008 + Peter Hutterer; Copyright (c) 2006 Adam Jackson; Copyright (c) + 2009 NVIDIA Corporation; Copyright (c) 1999 Keith Packard; + Copyright (c) 2007-2009 Red Hat, Inc.; Copyright (c) 2005-2008 + Daniel Stone; Copyright (c) 2006-2009 Simon Thum; Copyright + (c) 1987, 2003-2006, 2008-2009 Sun Microsystems, Inc.; + Copyright (c) 2006 Luc Verhaegen. For complete copyright + information, see the individual licenses. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X Window System Core + Protocol which is governed by the licenses in + <xref linkend="licX-Oracle" xrefstyle="template: %n" /> and + <xref linkend="licMIT-OpenGroup" xrefstyle="template: %n" /> and + <xref linkend="licX-DEC1" xrefstyle="template: %n" /> and + <xref linkend="licX-HP4" xrefstyle="template: %n" /> and + <xref linkend="licXFree86" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 1991, 2005, 2006, Oracle and/or its affiliates. + All rights reserved.; Copyright 1997 Metro Link Incorporated; + Copyright (c) 2005 Daniel Stone; Copyright (c) 1999 The + XFree86 Project Inc.; Copyright 1985-1991, 1993-1998 The Open + Group; Copyright 1987 by Apollo Computer Inc., Chelmsford, + Massachusetts.; Copyright 1987, 1988 by Digital Equipment + Corporation, Maynard, Massachusetts.; Copyright 1989 by + Hewlett-Packard Company.; Copyright 2005 Red Hat, Inc + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the xset utility which is + governed by the license in + <xref linkend="licMIT-OpenGroup" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 1985, 1988, 1998 The Open Group + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the libdrm library which is + governed by the license in + <xref linkend="licMIT" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 1999, 2000 Precision Insight, Inc., Cedar Park, Texas.; + Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California. + All Rights Reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the libdevmapper library + which is governed by the license in + <xref linkend="licGPL" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 2001-2004 Sistina Software, Inc. All rights + reserved.; Copyright (C) 2004-2017 Red Hat, Inc. All rights + reserved.; Copyright (C) 2006 Rackable Systems All rights + reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from DXVK Native which is + governed by the license in + <xref linkend="licZLIB" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2017-2021 Philip Rebohle; Copyright (c) + 2019-2021 Joshua Ashton + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from PulseAudio which is + governed by the license in + <xref linkend="licLGPL" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2017-2021 Philip Rebohle; Copyright (c) + 2019-2021 Joshua Ashton + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from libtpms which is + governed by the license in + <xref linkend="licTpms" xrefstyle="template: %n" /> and + </para> + + <para> + (c) Copyright IBM Corporation 2006 - 2011; + (c) Copyright IBM Corp. and others, 2012-2016 + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from libssh which is + governed by the license in + <xref linkend="licLGPL" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2004-2013 by Aris Adamantiadis; + Copyright (c) 2009-2013 by Andreas Schneider <asn@cryptomilk.org> + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="third-party-licenses"> + + <title>Third-Party Licenses</title> + + <sect2 id="licGPL"> + + <title>GNU General Public License (GPL)</title> + + <para> + GNU GENERAL PUBLIC LICENSE Version 2, June 1991 + </para> + + <para> + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + </para> + + <para> + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + </para> + + <para> + Everyone is permitted to copy and distribute verbatim copies of + this license document, but changing it is not allowed. + </para> + + <para> + Preamble + </para> + + <para> + The licenses for most software are designed to take away your + freedom to share and change it. By contrast, the GNU General + Public License is intended to guarantee your freedom to share + and change free software--to make sure the software is free for + all its users. This General Public License applies to most of + the Free Software Foundation's software and to any other program + whose authors commit to using it. (Some other Free Software + Foundation software is covered by the GNU Library General Public + License instead.) You can apply it to your programs, too. + </para> + + <para> + When we speak of free software, we are referring to freedom, not + price. Our General Public Licenses are designed to make sure + that you have the freedom to distribute copies of free software + (and charge for this service if you wish), that you receive + source code or can get it if you want it, that you can change + the software or use pieces of it in new free programs; and that + you know you can do these things. + </para> + + <para> + To protect your rights, we need to make restrictions that forbid + anyone to deny you these rights or to ask you to surrender the + rights. These restrictions translate to certain responsibilities + for you if you distribute copies of the software, or if you + modify it. + </para> + + <para> + For example, if you distribute copies of such a program, whether + gratis or for a fee, you must give the recipients all the rights + that you have. You must make sure that they, too, receive or can + get the source code. And you must show them these terms so they + know their rights. + </para> + + <para> + We protect your rights with two steps: (1) copyright the + software, and (2) offer you this license which gives you legal + permission to copy, distribute and/or modify the software. + </para> + + <para> + Also, for each author's protection and ours, we want to make + certain that everyone understands that there is no warranty for + this free software. If the software is modified by someone else + and passed on, we want its recipients to know that what they + have is not the original, so that any problems introduced by + others will not reflect on the original authors' reputations. + </para> + + <para> + Finally, any free program is threatened constantly by software + patents. We wish to avoid the danger that redistributors of a + free program will individually obtain patent licenses, in effect + making the program proprietary. To prevent this, we have made it + clear that any patent must be licensed for everyone's free use + or not licensed at all. + </para> + + <para> + The precise terms and conditions for copying, distribution and + modification follow. + </para> + + <para> + GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, + DISTRIBUTION AND MODIFICATION + </para> + + <para> + 0. This License applies to any program or other work which + contains a notice placed by the copyright holder saying it may + be distributed under the terms of this General Public License. + The "Program", below, refers to any such program or work, and a + "work based on the Program" means either the Program or any + derivative work under copyright law: that is to say, a work + containing the Program or a portion of it, either verbatim or + with modifications and/or translated into another language. + (Hereinafter, translation is included without limitation in the + term "modification".) Each licensee is addressed as "you". + </para> + + <para> + Activities other than copying, distribution and modification are + not covered by this License; they are outside its scope. The act + of running the Program is not restricted, and the output from + the Program is covered only if its contents constitute a work + based on the Program (independent of having been made by running + the Program). Whether that is true depends on what the Program + does. + </para> + + <para> + 1. You may copy and distribute verbatim copies of the Program's + source code as you receive it, in any medium, provided that you + conspicuously and appropriately publish on each copy an + appropriate copyright notice and disclaimer of warranty; keep + intact all the notices that refer to this License and to the + absence of any warranty; and give any other recipients of the + Program a copy of this License along with the Program. + </para> + + <para> + You may charge a fee for the physical act of transferring a + copy, and you may at your option offer warranty protection in + exchange for a fee. + </para> + + <para> + 2. You may modify your copy or copies of the Program or any + portion of it, thus forming a work based on the Program, and + copy and distribute such modifications or work under the terms + of Section 1 above, provided that you also meet all of these + conditions: + </para> + + <para> + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + </para> + + <para> + b) You must cause any work that you distribute or publish, that + in whole or in part contains or is derived from the Program or + any part thereof, to be licensed as a whole at no charge to all + third parties under the terms of this License. + </para> + + <para> + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you + provide a warranty) and that users may redistribute the program + under these conditions, and telling the user how to view a copy + of this License. (Exception: if the Program itself is + interactive but does not normally print such an announcement, + your work based on the Program is not required to print an + announcement.) + </para> + + <para> + These requirements apply to the modified work as a whole. If + identifiable sections of that work are not derived from the + Program, and can be reasonably considered independent and + separate works in themselves, then this License, and its terms, + do not apply to those sections when you distribute them as + separate works. But when you distribute the same sections as + part of a whole which is a work based on the Program, the + distribution of the whole must be on the terms of this License, + whose permissions for other licensees extend to the entire + whole, and thus to each and every part regardless of who wrote + it. + </para> + + <para> + Thus, it is not the intent of this section to claim rights or + contest your rights to work written entirely by you; rather, the + intent is to exercise the right to control the distribution of + derivative or collective works based on the Program. + </para> + + <para> + In addition, mere aggregation of another work not based on the + Program with the Program (or with a work based on the Program) + on a volume of a storage or distribution medium does not bring + the other work under the scope of this License. + </para> + + <para> + 3. You may copy and distribute the Program (or a work based on + it, under Section 2) in object code or executable form under the + terms of Sections 1 and 2 above provided that you also do one of + the following: + </para> + + <para> + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of + Sections 1 and 2 above on a medium customarily used for software + interchange; or, + </para> + + <para> + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a + medium customarily used for software interchange; or, + </para> + + <para> + c) Accompany it with the information you received as to the + offer to distribute corresponding source code. (This alternative + is allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + </para> + + <para> + The source code for a work means the preferred form of the work + for making modifications to it. For an executable work, complete + source code means all the source code for all modules it + contains, plus any associated interface definition files, plus + the scripts used to control compilation and installation of the + executable. However, as a special exception, the source code + distributed need not include anything that is normally + distributed (in either source or binary form) with the major + components (compiler, kernel, and so on) of the operating system + on which the executable runs, unless that component itself + accompanies the executable. + </para> + + <para> + If distribution of executable or object code is made by offering + access to copy from a designated place, then offering equivalent + access to copy the source code from the same place counts as + distribution of the source code, even though third parties are + not compelled to copy the source along with the object code. + </para> + + <para> + 4. You may not copy, modify, sublicense, or distribute the + Program except as expressly provided under this License. Any + attempt otherwise to copy, modify, sublicense or distribute the + Program is void, and will automatically terminate your rights + under this License. However, parties who have received copies, + or rights, from you under this License will not have their + licenses terminated so long as such parties remain in full + compliance. + </para> + + <para> + 5. You are not required to accept this License, since you have + not signed it. However, nothing else grants you permission to + modify or distribute the Program or its derivative works. These + actions are prohibited by law if you do not accept this License. + Therefore, by modifying or distributing the Program (or any work + based on the Program), you indicate your acceptance of this + License to do so, and all its terms and conditions for copying, + distributing or modifying the Program or works based on it. + </para> + + <para> + 6. Each time you redistribute the Program (or any work based on + the Program), the recipient automatically receives a license + from the original licensor to copy, distribute or modify the + Program subject to these terms and conditions. You may not + impose any further restrictions on the recipients' exercise of + the rights granted herein. You are not responsible for enforcing + compliance by third parties to this License. + </para> + + <para> + 7. If, as a consequence of a court judgment or allegation of + patent infringement or for any other reason (not limited to + patent issues), conditions are imposed on you (whether by court + order, agreement or otherwise) that contradict the conditions of + this License, they do not excuse you from the conditions of this + License. If you cannot distribute so as to satisfy + simultaneously your obligations under this License and any other + pertinent obligations, then as a consequence you may not + distribute the Program at all. For example, if a patent license + would not permit royalty-free redistribution of the Program by + all those who receive copies directly or indirectly through you, + then the only way you could satisfy both it and this License + would be to refrain entirely from distribution of the Program. + </para> + + <para> + If any portion of this section is held invalid or unenforceable + under any particular circumstance, the balance of the section is + intended to apply and the section as a whole is intended to + apply in other circumstances. + </para> + + <para> + It is not the purpose of this section to induce you to infringe + any patents or other property right claims or to contest + validity of any such claims; this section has the sole purpose + of protecting the integrity of the free software distribution + system, which is implemented by public license practices. Many + people have made generous contributions to the wide range of + software distributed through that system in reliance on + consistent application of that system; it is up to the + author/donor to decide if he or she is willing to distribute + software through any other system and a licensee cannot impose + that choice. + </para> + + <para> + This section is intended to make thoroughly clear what is + believed to be a consequence of the rest of this License. + </para> + + <para> + 8. If the distribution and/or use of the Program is restricted + in certain countries either by patents or by copyrighted + interfaces, the original copyright holder who places the Program + under this License may add an explicit geographical distribution + limitation excluding those countries, so that distribution is + permitted only in or among countries not thus excluded. In such + case, this License incorporates the limitation as if written in + the body of this License. + </para> + + <para> + 9. The Free Software Foundation may publish revised and/or new + versions of the General Public License from time to time. Such + new versions will be similar in spirit to the present version, + but may differ in detail to address new problems or concerns. + </para> + + <para> + Each version is given a distinguishing version number. If the + Program specifies a version number of this License which applies + to it and "any later version", you have the option of following + the terms and conditions either of that version or of any later + version published by the Free Software Foundation. If the + Program does not specify a version number of this License, you + may choose any version ever published by the Free Software + Foundation. + </para> + + <para> + 10. If you wish to incorporate parts of the Program into other + free programs whose distribution conditions are different, write + to the author to ask for permission. For software which is + copyrighted by the Free Software Foundation, write to the Free + Software Foundation; we sometimes make exceptions for this. Our + decision will be guided by the two goals of preserving the free + status of all derivatives of our free software and of promoting + the sharing and reuse of software generally. + </para> + + <para> + NO WARRANTY + </para> + + <para> + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO + WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE + LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT + HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT + WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, + BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE + QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE + PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY + SERVICING, REPAIR OR CORRECTION. + </para> + + <para> + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO + IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY + MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE + LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, + INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR + INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS + OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY + YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH + ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + </para> + + <para> + END OF TERMS AND CONDITIONS + </para> + + </sect2> + + <sect2 id="licLGPL"> + + <title>GNU Lesser General Public License (LGPL)</title> + + <para> + GNU LESSER GENERAL PUBLIC LICENSE Version 2.1, February 1999 + </para> + + <para> + Copyright (C) 1991, 1999 Free Software Foundation, Inc. 59 + Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is + permitted to copy and distribute verbatim copies of this license + document, but changing it is not allowed. + </para> + + <para> + [This is the first released version of the Lesser GPL. It also + counts as the successor of the GNU Library Public License, + version 2, hence the version number 2.1.] + </para> + + <para> + Preamble + </para> + + <para> + The licenses for most software are designed to take away your + freedom to share and change it. By contrast, the GNU General + Public Licenses are intended to guarantee your freedom to share + and change free software--to make sure the software is free for + all its users. + </para> + + <para> + This license, the Lesser General Public License, applies to some + specially designated software packages--typically libraries--of + the Free Software Foundation and other authors who decide to use + it. You can use it too, but we suggest you first think carefully + about whether this license or the ordinary General Public + License is the better strategy to use in any particular case, + based on the explanations below. + </para> + + <para> + When we speak of free software, we are referring to freedom of + use, not price. Our General Public Licenses are designed to make + sure that you have the freedom to distribute copies of free + software (and charge for this service if you wish); that you + receive source code or can get it if you want it; that you can + change the software and use pieces of it in new free programs; + and that you are informed that you can do these things. + </para> + + <para> + To protect your rights, we need to make restrictions that forbid + distributors to deny you these rights or to ask you to surrender + these rights. These restrictions translate to certain + responsibilities for you if you distribute copies of the library + or if you modify it. + </para> + + <para> + For example, if you distribute copies of the library, whether + gratis or for a fee, you must give the recipients all the rights + that we gave you. You must make sure that they, too, receive or + can get the source code. If you link other code with the + library, you must provide complete object files to the + recipients, so that they can relink them with the library after + making changes to the library and recompiling it. And you must + show them these terms so they know their rights. + </para> + + <para> + We protect your rights with a two-step method: (1) we copyright + the library, and (2) we offer you this license, which gives you + legal permission to copy, distribute and/or modify the library. + </para> + + <para> + To protect each distributor, we want to make it very clear that + there is no warranty for the free library. Also, if the library + is modified by someone else and passed on, the recipients should + know that what they have is not the original version, so that + the original author's reputation will not be affected by + problems that might be introduced by others. + </para> + + <para> + Finally, software patents pose a constant threat to the + existence of any free program. We wish to make sure that a + company cannot effectively restrict the users of a free program + by obtaining a restrictive license from a patent holder. + Therefore, we insist that any patent license obtained for a + version of the library must be consistent with the full freedom + of use specified in this license. + </para> + + <para> + Most GNU software, including some libraries, is covered by the + ordinary GNU General Public License. This license, the GNU + Lesser General Public License, applies to certain designated + libraries, and is quite different from the ordinary General + Public License. We use this license for certain libraries in + order to permit linking those libraries into non-free programs. + </para> + + <para> + When a program is linked with a library, whether statically or + using a shared library, the combination of the two is legally + speaking a combined work, a derivative of the original library. + The ordinary General Public License therefore permits such + linking only if the entire combination fits its criteria of + freedom. The Lesser General Public License permits more lax + criteria for linking other code with the library. + </para> + + <para> + We call this license the "Lesser" General Public License because + it does Less to protect the user's freedom than the ordinary + General Public License. It also provides other free software + developers Less of an advantage over competing non-free + programs. These disadvantages are the reason we use the ordinary + General Public License for many libraries. However, the Lesser + license provides advantages in certain special circumstances. + </para> + + <para> + For example, on rare occasions, there may be a special need to + encourage the widest possible use of a certain library, so that + it becomes a de-facto standard. To achieve this, non-free + programs must be allowed to use the library. A more frequent + case is that a free library does the same job as widely used + non-free libraries. In this case, there is little to gain by + limiting the free library to free software only, so we use the + Lesser General Public License. + </para> + + <para> + In other cases, permission to use a particular library in + non-free programs enables a greater number of people to use a + large body of free software. For example, permission to use the + GNU C Library in non-free programs enables many more people to + use the whole GNU operating system, as well as its variant, the + GNU/Linux operating system. + </para> + + <para> + Although the Lesser General Public License is Less protective of + the users' freedom, it does ensure that the user of a program + that is linked with the Library has the freedom and the + wherewithal to run that program using a modified version of the + Library. + </para> + + <para> + The precise terms and conditions for copying, distribution and + modification follow. Pay close attention to the difference + between a "work based on the library" and a "work that uses the + library". The former contains code derived from the library, + whereas the latter must be combined with the library in order to + run. + </para> + + <para> + GNU LESSER GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR + COPYING, DISTRIBUTION AND MODIFICATION + </para> + + <para> + 0. This License Agreement applies to any software library or + other program which contains a notice placed by the copyright + holder or other authorized party saying it may be distributed + under the terms of this Lesser General Public License (also + called "this License"). Each licensee is addressed as "you". + </para> + + <para> + A "library" means a collection of software functions and/or data + prepared so as to be conveniently linked with application + programs (which use some of those functions and data) to form + executables. + </para> + + <para> + The "Library", below, refers to any such software library or + work which has been distributed under these terms. A "work based + on the Library" means either the Library or any derivative work + under copyright law: that is to say, a work containing the + Library or a portion of it, either verbatim or with + modifications and/or translated straightforwardly into another + language. (Hereinafter, translation is included without + limitation in the term "modification".) + </para> + + <para> + "Source code" for a work means the preferred form of the work + for making modifications to it. For a library, complete source + code means all the source code for all modules it contains, plus + any associated interface definition files, plus the scripts used + to control compilation and installation of the library. + </para> + + <para> + Activities other than copying, distribution and modification are + not covered by this License; they are outside its scope. The act + of running a program using the Library is not restricted, and + output from such a program is covered only if its contents + constitute a work based on the Library (independent of the use + of the Library in a tool for writing it). Whether that is true + depends on what the Library does and what the program that uses + the Library does. + </para> + + <para> + 1. You may copy and distribute verbatim copies of the Library's + complete source code as you receive it, in any medium, provided + that you conspicuously and appropriately publish on each copy an + appropriate copyright notice and disclaimer of warranty; keep + intact all the notices that refer to this License and to the + absence of any warranty; and distribute a copy of this License + along with the Library. + </para> + + <para> + You may charge a fee for the physical act of transferring a + copy, and you may at your option offer warranty protection in + exchange for a fee. + </para> + + <para> + 2. You may modify your copy or copies of the Library or any + portion of it, thus forming a work based on the Library, and + copy and distribute such modifications or work under the terms + of Section 1 above, provided that you also meet all of these + conditions: + </para> + + <para> + a) The modified work must itself be a software library. + </para> + + <para> + b) You must cause the files modified to carry prominent notices + stating that you changed the files and the date of any change. + </para> + + <para> + c) You must cause the whole of the work to be licensed at no + charge to all third parties under the terms of this License. + </para> + + <para> + d) If a facility in the modified Library refers to a function or + a table of data to be supplied by an application program that + uses the facility, other than as an argument passed when the + facility is invoked, then you must make a good faith effort to + ensure that, in the event an application does not supply such + function or table, the facility still operates, and performs + whatever part of its purpose remains meaningful. + </para> + + <para> + (For example, a function in a library to compute square roots + has a purpose that is entirely well-defined independent of the + application. Therefore, Subsection 2d requires that any + application-supplied function or table used by this function + must be optional: if the application does not supply it, the + square root function must still compute square roots.) + </para> + + <para> + These requirements apply to the modified work as a whole. If + identifiable sections of that work are not derived from the + Library, and can be reasonably considered independent and + separate works in themselves, then this License, and its terms, + do not apply to those sections when you distribute them as + separate works. But when you distribute the same sections as + part of a whole which is a work based on the Library, the + distribution of the whole must be on the terms of this License, + whose permissions for other licensees extend to the entire + whole, and thus to each and every part regardless of who wrote + it. + </para> + + <para> + Thus, it is not the intent of this section to claim rights or + contest your rights to work written entirely by you; rather, the + intent is to exercise the right to control the distribution of + derivative or collective works based on the Library. + </para> + + <para> + In addition, mere aggregation of another work not based on the + Library with the Library (or with a work based on the Library) + on a volume of a storage or distribution medium does not bring + the other work under the scope of this License. + </para> + + <para> + 3. You may opt to apply the terms of the ordinary GNU General + Public License instead of this License to a given copy of the + Library. To do this, you must alter all the notices that refer + to this License, so that they refer to the ordinary GNU General + Public License, version 2, instead of to this License. (If a + newer version than version 2 of the ordinary GNU General Public + License has appeared, then you can specify that version instead + if you wish.) Do not make any other change in these notices. + </para> + + <para> + Once this change is made in a given copy, it is irreversible for + that copy, so the ordinary GNU General Public License applies to + all subsequent copies and derivative works made from that copy. + </para> + + <para> + This option is useful when you wish to copy part of the code of + the Library into a program that is not a library. + </para> + + <para> + 4. You may copy and distribute the Library (or a portion or + derivative of it, under Section 2) in object code or executable + form under the terms of Sections 1 and 2 above provided that you + accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of + Sections 1 and 2 above on a medium customarily used for software + interchange. + </para> + + <para> + If distribution of object code is made by offering access to + copy from a designated place, then offering equivalent access to + copy the source code from the same place satisfies the + requirement to distribute the source code, even though third + parties are not compelled to copy the source along with the + object code. + </para> + + <para> + 5. A program that contains no derivative of any portion of the + Library, but is designed to work with the Library by being + compiled or linked with it, is called a "work that uses the + Library". Such a work, in isolation, is not a derivative work of + the Library, and therefore falls outside the scope of this + License. + </para> + + <para> + However, linking a "work that uses the Library" with the Library + creates an executable that is a derivative of the Library + (because it contains portions of the Library), rather than a + "work that uses the library". The executable is therefore + covered by this License. Section 6 states terms for distribution + of such executables. + </para> + + <para> + When a "work that uses the Library" uses material from a header + file that is part of the Library, the object code for the work + may be a derivative work of the Library even though the source + code is not. Whether this is true is especially significant if + the work can be linked without the Library, or if the work is + itself a library. The threshold for this to be true is not + precisely defined by law. + </para> + + <para> + If such an object file uses only numerical parameters, data + structure layouts and accessors, and small macros and small + inline functions (ten lines or less in length), then the use of + the object file is unrestricted, regardless of whether it is + legally a derivative work. (Executables containing this object + code plus portions of the Library will still fall under Section + 6.) Otherwise, if the work is a derivative of the Library, you + may distribute the object code for the work under the terms of + Section 6. Any executables containing that work also fall under + Section 6, whether or not they are linked directly with the + Library itself. + </para> + + <para> + 6. As an exception to the Sections above, you may also combine + or link a "work that uses the Library" with the Library to + produce a work containing portions of the Library, and + distribute that work under terms of your choice, provided that + the terms permit modification of the work for the customer's own + use and reverse engineering for debugging such modifications. + </para> + + <para> + You must give prominent notice with each copy of the work that + the Library is used in it and that the Library and its use are + covered by this License. You must supply a copy of this License. + If the work during execution displays copyright notices, you + must include the copyright notice for the Library among them, as + well as a reference directing the user to the copy of this + License. Also, you must do one of these things: + </para> + + <para> + a) Accompany the work with the complete corresponding + machine-readable source code for the Library including whatever + changes were used in the work (which must be distributed under + Sections 1 and 2 above); and, if the work is an executable + linked with the Library, with the complete machine-readable + "work that uses the Library", as object code and/or source code, + so that the user can modify the Library and then relink to + produce a modified executable containing the modified Library. + (It is understood that the user who changes the contents of + definitions files in the Library will not necessarily be able to + recompile the application to use the modified definitions.) + </para> + + <para> + b) Use a suitable shared library mechanism for linking with the + Library. A suitable mechanism is one that (1) uses at run time a + copy of the library already present on the user's computer + system, rather than copying library functions into the + executable, and (2) will operate properly with a modified + version of the library, if the user installs one, as long as the + modified version is interface-compatible with the version that + the work was made with. + </para> + + <para> + c) Accompany the work with a written offer, valid for at least + three years, to give the same user the materials specified in + Subsection 6a, above, for a charge no more than the cost of + performing this distribution. + </para> + + <para> + d) If distribution of the work is made by offering access to + copy from a designated place, offer equivalent access to copy + the above specified materials from the same place. + </para> + + <para> + e) Verify that the user has already received a copy of these + materials or that you have already sent this user a copy. + </para> + + <para> + For an executable, the required form of the "work that uses the + Library" must include any data and utility programs needed for + reproducing the executable from it. However, as a special + exception, the materials to be distributed need not include + anything that is normally distributed (in either source or + binary form) with the major components (compiler, kernel, and so + on) of the operating system on which the executable runs, unless + that component itself accompanies the executable. + </para> + + <para> + It may happen that this requirement contradicts the license + restrictions of other proprietary libraries that do not normally + accompany the operating system. Such a contradiction means you + cannot use both them and the Library together in an executable + that you distribute. + </para> + + <para> + 7. You may place library facilities that are a work based on the + Library side-by-side in a single library together with other + library facilities not covered by this License, and distribute + such a combined library, provided that the separate distribution + of the work based on the Library and of the other library + facilities is otherwise permitted, and provided that you do + these two things: + </para> + + <para> + a) Accompany the combined library with a copy of the same work + based on the Library, uncombined with any other library + facilities. This must be distributed under the terms of the + Sections above. + </para> + + <para> + b) Give prominent notice with the combined library of the fact + that part of it is a work based on the Library, and explaining + where to find the accompanying uncombined form of the same work. + </para> + + <para> + 8. You may not copy, modify, sublicense, link with, or + distribute the Library except as expressly provided under this + License. Any attempt otherwise to copy, modify, sublicense, link + with, or distribute the Library is void, and will automatically + terminate your rights under this License. However, parties who + have received copies, or rights, from you under this License + will not have their licenses terminated so long as such parties + remain in full compliance. + </para> + + <para> + 9. You are not required to accept this License, since you have + not signed it. However, nothing else grants you permission to + modify or distribute the Library or its derivative works. These + actions are prohibited by law if you do not accept this License. + Therefore, by modifying or distributing the Library (or any work + based on the Library), you indicate your acceptance of this + License to do so, and all its terms and conditions for copying, + distributing or modifying the Library or works based on it. + </para> + + <para> + 10. Each time you redistribute the Library (or any work based on + the Library), the recipient automatically receives a license + from the original licensor to copy, distribute, link with or + modify the Library subject to these terms and conditions. You + may not impose any further restrictions on the recipients' + exercise of the rights granted herein. You are not responsible + for enforcing compliance by third parties with this License. + </para> + + <para> + 11. If, as a consequence of a court judgment or allegation of + patent infringement or for any other reason (not limited to + patent issues), conditions are imposed on you (whether by court + order, agreement or otherwise) that contradict the conditions of + this License, they do not excuse you from the conditions of this + License. If you cannot distribute so as to satisfy + simultaneously your obligations under this License and any other + pertinent obligations, then as a consequence you may not + distribute the Library at all. For example, if a patent license + would not permit royalty-free redistribution of the Library by + all those who receive copies directly or indirectly through you, + then the only way you could satisfy both it and this License + would be to refrain entirely from distribution of the Library. + </para> + + <para> + If any portion of this section is held invalid or unenforceable + under any particular circumstance, the balance of the section is + intended to apply, and the section as a whole is intended to + apply in other circumstances. + </para> + + <para> + It is not the purpose of this section to induce you to infringe + any patents or other property right claims or to contest + validity of any such claims; this section has the sole purpose + of protecting the integrity of the free software distribution + system which is implemented by public license practices. Many + people have made generous contributions to the wide range of + software distributed through that system in reliance on + consistent application of that system; it is up to the + author/donor to decide if he or she is willing to distribute + software through any other system and a licensee cannot impose + that choice. + </para> + + <para> + This section is intended to make thoroughly clear what is + believed to be a consequence of the rest of this License. + </para> + + <para> + 12. If the distribution and/or use of the Library is restricted + in certain countries either by patents or by copyrighted + interfaces, the original copyright holder who places the Library + under this License may add an explicit geographical distribution + limitation excluding those countries, so that distribution is + permitted only in or among countries not thus excluded. In such + case, this License incorporates the limitation as if written in + the body of this License. + </para> + + <para> + 13. The Free Software Foundation may publish revised and/or new + versions of the Lesser General Public License from time to time. + Such new versions will be similar in spirit to the present + version, but may differ in detail to address new problems or + concerns. + </para> + + <para> + Each version is given a distinguishing version number. If the + Library specifies a version number of this License which applies + to it and "any later version", you have the option of following + the terms and conditions either of that version or of any later + version published by the Free Software Foundation. If the + Library does not specify a license version number, you may + choose any version ever published by the Free Software + Foundation. + </para> + + <para> + 14. If you wish to incorporate parts of the Library into other + free programs whose distribution conditions are incompatible + with these, write to the author to ask for permission. For + software which is copyrighted by the Free Software Foundation, + write to the Free Software Foundation; we sometimes make + exceptions for this. Our decision will be guided by the two + goals of preserving the free status of all derivatives of our + free software and of promoting the sharing and reuse of software + generally. + </para> + + <para> + NO WARRANTY + </para> + + <para> + 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO + WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE + LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT + HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT + WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, + BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE + QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE + LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY + SERVICING, REPAIR OR CORRECTION. + </para> + + <para> + 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO + IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY + MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE + LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, + INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR + INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS + OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY + YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH + ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + </para> + + <para> + END OF TERMS AND CONDITIONS + </para> + + </sect2> + + <sect2 id="licMPL"> + + <title>Mozilla Public License (MPL)</title> + + <para> + MOZILLA PUBLIC LICENSE Version 1.1 + </para> + + <para> + 1. Definitions. + </para> + + <para> + 1.0.1. "Commercial Use" means distribution or otherwise making + the Covered Code available to a third party. + </para> + + <para> + 1.1. "Contributor" means each entity that creates or contributes + to the creation of Modifications. + </para> + + <para> + 1.2. "Contributor Version" means the combination of the Original + Code, prior Modifications used by a Contributor, and the + Modifications made by that particular Contributor. + </para> + + <para> + 1.3. "Covered Code" means the Original Code or Modifications or + the combination of the Original Code and Modifications, in each + case including portions thereof. + </para> + + <para> + 1.4. "Electronic Distribution Mechanism" means a mechanism + generally accepted in the software development community for the + electronic transfer of data. + </para> + + <para> + 1.5. "Executable" means Covered Code in any form other than + Source Code. + </para> + + <para> + 1.6. "Initial Developer" means the individual or entity + identified as the Initial Developer in the Source Code notice + required by Exhibit A. + </para> + + <para> + 1.7. "Larger Work" means a work which combines Covered Code or + portions thereof with code not governed by the terms of this + License. + </para> + + <para> + 1.8. "License" means this document. + </para> + + <para> + 1.8.1. "Licensable" means having the right to grant, to the + maximum extent possible, whether at the time of the initial + grant or subsequently acquired, any and all of the rights + conveyed herein. + </para> + + <para> + 1.9. "Modifications" means any addition to or deletion from the + substance or structure of either the Original Code or any + previous Modifications. When Covered Code is released as a + series of files, a Modification is: + </para> + + <para> + A. Any addition to or deletion from the contents of a file + containing Original Code or previous Modifications. + </para> + + <para> + B. Any new file that contains any part of the Original Code or + previous Modifications. + </para> + + <para> + 1.10. "Original Code" means Source Code of computer software + code which is described in the Source Code notice required by + Exhibit A as Original Code, and which, at the time of its + release under this License is not already Covered Code governed + by this License. + </para> + + <para> + 1.10.1. "Patent Claims" means any patent claim(s), now owned or + hereafter acquired, including without limitation, method, + process, and apparatus claims, in any patent Licensable by + grantor. + </para> + + <para> + 1.11. "Source Code" means the preferred form of the Covered Code + for making modifications to it, including all modules it + contains, plus any associated interface definition files, + scripts used to control compilation and installation of an + Executable, or source code differential comparisons against + either the Original Code or another well known, available + Covered Code of the Contributor's choice. The Source Code can be + in a compressed or archival form, provided the appropriate + decompression or de-archiving software is widely available for + no charge. + </para> + + <para> + 1.12. "You" (or "Your") means an individual or a legal entity + exercising rights under, and complying with all of the terms of, + this License or a future version of this License issued under + Section 6.1. For legal entities, "You" includes any entity which + controls, is controlled by, or is under common control with You. + For purposes of this definition, "control" means (a) the power, + direct or indirect, to cause the direction or management of such + entity, whether by contract or otherwise, or (b) ownership of + more than fifty percent (50%) of the outstanding shares or + beneficial ownership of such entity. + </para> + + <para> + 2. Source Code License. + </para> + + <para> + 2.1. The Initial Developer Grant. The Initial Developer hereby + grants You a world-wide, royalty-free, non-exclusive license, + subject to third party intellectual property claims: + </para> + + <para> + (a) under intellectual property rights (other than patent or + trademark) Licensable by Initial Developer to use, reproduce, + modify, display, perform, sublicense and distribute the Original + Code (or portions thereof) with or without Modifications, and/or + as part of a Larger Work; and + </para> + + <para> + (b) under Patents Claims infringed by the making, using or + selling of Original Code, to make, have made, use, practice, + sell, and offer for sale, and/or otherwise dispose of the + Original Code (or portions thereof). + </para> + + <para> + (c) the licenses granted in this Section 2.1(a) and (b) are + effective on the date Initial Developer first distributes + Original Code under the terms of this License. + </para> + + <para> + (d) Notwithstanding Section 2.1(b) above, no patent license is + granted: 1) for code that You delete from the Original Code; 2) + separate from the Original Code; or 3) for infringements caused + by: i) the modification of the Original Code or ii) the + combination of the Original Code with other software or devices. + </para> + + <para> + 2.2. Contributor Grant. Subject to third party intellectual + property claims, each Contributor hereby grants You a + world-wide, royalty-free, non-exclusive license + </para> + + <para> + (a) under intellectual property rights (other than patent or + trademark) Licensable by Contributor, to use, reproduce, modify, + display, perform, sublicense and distribute the Modifications + created by such Contributor (or portions thereof) either on an + unmodified basis, with other Modifications, as Covered Code + and/or as part of a Larger Work; and + </para> + + <para> + (b) under Patent Claims infringed by the making, using, or + selling of Modifications made by that Contributor either alone + and/or in combination with its Contributor Version (or portions + of such combination), to make, use, sell, offer for sale, have + made, and/or otherwise dispose of: 1) Modifications made by that + Contributor (or portions thereof); and 2) the combination of + Modifications made by that Contributor with its Contributor + Version (or portions of such combination). + </para> + + <para> + (c) the licenses granted in Sections 2.2(a) and 2.2(b) are + effective on the date Contributor first makes Commercial Use of + the Covered Code. + </para> + + <para> + (d) Notwithstanding Section 2.2(b) above, no patent license is + granted: 1) for any code that Contributor has deleted from the + Contributor Version; 2) separate from the Contributor Version; + 3) for infringements caused by: i) third party modifications of + Contributor Version or ii) the combination of Modifications made + by that Contributor with other software (except as part of the + Contributor Version) or other devices; or 4) under Patent Claims + infringed by Covered Code in the absence of Modifications made + by that Contributor. + </para> + + <para> + 3. Distribution Obligations. + </para> + + <para> + 3.1. Application of License. The Modifications which You create + or to which You contribute are governed by the terms of this + License, including without limitation Section 2.2. The Source + Code version of Covered Code may be distributed only under the + terms of this License or a future version of this License + released under Section 6.1, and You must include a copy of this + License with every copy of the Source Code You distribute. You + may not offer or impose any terms on any Source Code version + that alters or restricts the applicable version of this License + or the recipients' rights hereunder. However, You may include an + additional document offering the additional rights described in + Section 3.5. + </para> + + <para> + 3.2. Availability of Source Code. Any Modification which You + create or to which You contribute must be made available in + Source Code form under the terms of this License either on the + same media as an Executable version or via an accepted + Electronic Distribution Mechanism to anyone to whom you made an + Executable version available; and if made available via + Electronic Distribution Mechanism, must remain available for at + least twelve (12) months after the date it initially became + available, or at least six (6) months after a subsequent version + of that particular Modification has been made available to such + recipients. You are responsible for ensuring that the Source + Code version remains available even if the Electronic + Distribution Mechanism is maintained by a third party. + </para> + + <para> + 3.3. Description of Modifications. You must cause all Covered + Code to which You contribute to contain a file documenting the + changes You made to create that Covered Code and the date of any + change. You must include a prominent statement that the + Modification is derived, directly or indirectly, from Original + Code provided by the Initial Developer and including the name of + the Initial Developer in (a) the Source Code, and (b) in any + notice in an Executable version or related documentation in + which You describe the origin or ownership of the Covered Code. + </para> + + <para> + 3.4. Intellectual Property Matters + </para> + + <para> + (a) Third Party Claims. If Contributor has knowledge that a + license under a third party's intellectual property rights is + required to exercise the rights granted by such Contributor + under Sections 2.1 or 2.2, Contributor must include a text file + with the Source Code distribution titled "LEGAL" which describes + the claim and the party making the claim in sufficient detail + that a recipient will know whom to contact. If Contributor + obtains such knowledge after the Modification is made available + as described in Section 3.2, Contributor shall promptly modify + the LEGAL file in all copies Contributor makes available + thereafter and shall take other steps (such as notifying + appropriate mailing lists or newsgroups) reasonably calculated + to inform those who received the Covered Code that new knowledge + has been obtained. + </para> + + <para> + (b) Contributor APIs. If Contributor's Modifications include an + application programming interface and Contributor has knowledge + of patent licenses which are reasonably necessary to implement + that API, Contributor must also include this information in the + LEGAL file. + </para> + + <para> + 3.5. Required Notices. You must duplicate the notice in Exhibit + A in each file of the Source Code. If it is not possible to put + such notice in a particular Source Code file due to its + structure, then You must include such notice in a location (such + as a relevant directory) where a user would be likely to look + for such a notice. If You created one or more Modification(s) + You may add your name as a Contributor to the notice described + in Exhibit A. You must also duplicate this License in any + documentation for the Source Code where You describe recipients' + rights or ownership rights relating to Covered Code. You may + choose to offer, and to charge a fee for, warranty, support, + indemnity or liability obligations to one or more recipients of + Covered Code. However, You may do so only on Your own behalf, + and not on behalf of the Initial Developer or any Contributor. + You must make it absolutely clear than any such warranty, + support, indemnity or liability obligation is offered by You + alone, and You hereby agree to indemnify the Initial Developer + and every Contributor for any liability incurred by the Initial + Developer or such Contributor as a result of warranty, support, + indemnity or liability terms You offer. + </para> + + <para> + 3.6. Distribution of Executable Versions. You may distribute + Covered Code in Executable form only if the requirements of + Section 3.1-3.5 have been met for that Covered Code, and if You + include a notice stating that the Source Code version of the + Covered Code is available under the terms of this License, + including a description of how and where You have fulfilled the + obligations of Section 3.2. The notice must be conspicuously + included in any notice in an Executable version, related + documentation or collateral in which You describe recipients' + rights relating to the Covered Code. You may distribute the + Executable version of Covered Code or ownership rights under a + license of Your choice, which may contain terms different from + this License, provided that You are in compliance with the terms + of this License and that the license for the Executable version + does not attempt to limit or alter the recipient's rights in the + Source Code version from the rights set forth in this License. + If You distribute the Executable version under a different + license You must make it absolutely clear that any terms which + differ from this License are offered by You alone, not by the + Initial Developer or any Contributor. You hereby agree to + indemnify the Initial Developer and every Contributor for any + liability incurred by the Initial Developer or such Contributor + as a result of any such terms You offer. + </para> + + <para> + 3.7. Larger Works. You may create a Larger Work by combining + Covered Code with other code not governed by the terms of this + License and distribute the Larger Work as a single product. In + such a case, You must make sure the requirements of this License + are fulfilled for the Covered Code. + </para> + + <para> + 4. Inability to Comply Due to Statute or Regulation.If it is + impossible for You to comply with any of the terms of this + License with respect to some or all of the Covered Code due to + statute, judicial order, or regulation then You must: (a) comply + with the terms of this License to the maximum extent possible; + and (b) describe the limitations and the code they affect. Such + description must be included in the LEGAL file described in + Section 3.4 and must be included with all distributions of the + Source Code. Except to the extent prohibited by statute or + regulation, such description must be sufficiently detailed for a + recipient of ordinary skill to be able to understand it. + </para> + + <para> + 5. Application of this License. This License applies to code to + which the Initial Developer has attached the notice in Exhibit A + and to related Covered Code. + </para> + + <para> + 6. Versions of the License. + </para> + + <para> + 6.1. New Versions. Netscape Communications Corporation + ("Netscape") may publish revised and/or new versions of the + License from time to time. Each version will be given a + distinguishing version number. + </para> + + <para> + 6.2. Effect of New Versions. Once Covered Code has been + published under a particular version of the License, You may + always continue to use it under the terms of that version. You + may also choose to use such Covered Code under the terms of any + subsequent version of the License published by Netscape. No one + other than Netscape has the right to modify the terms applicable + to Covered Code created under this License. + </para> + + <para> + 6.3. Derivative Works. If You create or use a modified version + of this License (which you may only do in order to apply it to + code which is not already Covered Code governed by this + License), You must (a) rename Your license so that the phrases + "Mozilla", "MOZILLAPL", "MOZPL", "Netscape", "MPL", "NPL" or any + confusingly similar phrase do not appear in your license (except + to note that your license differs from this License) and (b) + otherwise make it clear that Your version of the license + contains terms which differ from the Mozilla Public License and + Netscape Public License. (Filling in the name of the Initial + Developer, Original Code or Contributor in the notice described + in Exhibit A shall not of themselves be deemed to be + modifications of this License.) + </para> + + <para> + 7. DISCLAIMER OF WARRANTY. + </para> + + <para> + COVERED CODE IS PROVIDED UNDER THIS LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, + INCLUDING, WITHOUT LIMITATION, WARRANTIES THAT THE COVERED CODE + IS FREE OF DEFECTS, MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE + OR NON-INFRINGING. THE ENTIRE RISK AS TO THE QUALITY AND + PERFORMANCE OF THE COVERED CODE IS WITH YOU. SHOULD ANY COVERED + CODE PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE INITIAL + DEVELOPER OR ANY OTHER CONTRIBUTOR) ASSUME THE COST OF ANY + NECESSARY SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER OF + WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS LICENSE. NO USE + OF ANY COVERED CODE IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS + DISCLAIMER. + </para> + + <para> + 8. TERMINATION. + </para> + + <para> + 8.1. This License and the rights granted hereunder will + terminate automatically if You fail to comply with terms herein + and fail to cure such breach within 30 days of becoming aware of + the breach. All sublicenses to the Covered Code which are + properly granted shall survive any termination of this License. + Provisions which, by their nature, must remain in effect beyond + the termination of this License shall survive. + </para> + + <para> + 8.2. If You initiate litigation by asserting a patent + infringement claim (excluding declaratory judgment actions) + against Initial Developer or a Contributor (the Initial + Developer or Contributor against whom You file such action is + referred to as "Participant") alleging that: + </para> + + <para> + (a) such Participant's Contributor Version directly or + indirectly infringes any patent, then any and all rights granted + by such Participant to You under Sections 2.1 and/or 2.2 of this + License shall, upon 60 days notice from Participant terminate + prospectively, unless if within 60 days after receipt of notice + You either: (i) agree in writing to pay Participant a mutually + agreeable reasonable royalty for Your past and future use of + Modifications made by such Participant, or (ii) withdraw Your + litigation claim with respect to the Contributor Version against + such Participant. If within 60 days of notice, a reasonable + royalty and payment arrangement are not mutually agreed upon in + writing by the parties or the litigation claim is not withdrawn, + the rights granted by Participant to You under Sections 2.1 + and/or 2.2 automatically terminate at the expiration of the 60 + day notice period specified above. + </para> + + <para> + (b) any software, hardware, or device, other than such + Participant's Contributor Version, directly or indirectly + infringes any patent, then any rights granted to You by such + Participant under Sections 2.1(b) and 2.2(b) are revoked + effective as of the date You first made, used, sold, + distributed, or had made, Modifications made by that + Participant. + </para> + + <para> + 8.3. If You assert a patent infringement claim against + Participant alleging that such Participant's Contributor Version + directly or indirectly infringes any patent where such claim is + resolved (such as by license or settlement) prior to the + initiation of patent infringement litigation, then the + reasonable value of the licenses granted by such Participant + under Sections 2.1 or 2.2 shall be taken into account in + determining the amount or value of any payment or license. + </para> + + <para> + 8.4. In the event of termination under Sections 8.1 or 8.2 + above, all end user license agreements (excluding distributors + and resellers) which have been validly granted by You or any + distributor hereunder prior to termination shall survive + termination. + </para> + + <para> + 9. LIMITATION OF LIABILITY. UNDER NO CIRCUMSTANCES AND UNDER NO + LEGAL THEORY, WHETHER TORT (INCLUDING NEGLIGENCE), CONTRACT, OR + OTHERWISE, SHALL YOU, THE INITIAL DEVELOPER, ANY OTHER + CONTRIBUTOR, OR ANY DISTRIBUTOR OF COVERED CODE, OR ANY SUPPLIER + OF ANY OF SUCH PARTIES, BE LIABLE TO ANY PERSON FOR ANY + INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY + CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF + GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY + AND ALL OTHER COMMERCIAL DAMAGES OR LOSSES, EVEN IF SUCH PARTY + SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES. + THIS LIMITATION OF LIABILITY SHALL NOT APPLY TO LIABILITY FOR + DEATH OR PERSONAL INJURY RESULTING FROM SUCH PARTY'S NEGLIGENCE + TO THE EXTENT APPLICABLE LAW PROHIBITS SUCH LIMITATION. SOME + JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF + INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THIS EXCLUSION AND + LIMITATION MAY NOT APPLY TO YOU. + </para> + + <para> + 10. U.S. GOVERNMENT END USERS. The Covered Code is a "commercial + item," as that term is defined in 48 C.F.R. 2.101 (Oct. 1995), + consisting of "commercial computer software" and "commercial + computer software documentation," as such terms are used in 48 + C.F.R. 12.212 (Sept. 1995). Consistent with 48 C.F.R. 12.212 and + 48 C.F.R. 227.7202-1 through 227.7202-4 (June 1995), all U.S. + Government End Users acquire Covered Code with only those rights + set forth herein. + </para> + + <para> + 11. MISCELLANEOUS. This License represents the complete + agreement concerning subject matter hereof. If any provision of + this License is held to be unenforceable, such provision shall + be reformed only to the extent necessary to make it enforceable. + This License shall be governed by California law provisions + (except to the extent applicable law, if any, provides + otherwise), excluding its conflict-of-law provisions. With + respect to disputes in which at least one party is a citizen of, + or an entity chartered or registered to do business in the + United States of America, any litigation relating to this + License shall be subject to the jurisdiction of the Federal + Courts of the Northern District of California, with venue lying + in Santa Clara County, California, with the losing party + responsible for costs, including without limitation, court costs + and reasonable attorneys' fees and expenses. The application of + the United Nations Convention on Contracts for the International + Sale of Goods is expressly excluded. Any law or regulation which + provides that the language of a contract shall be construed + against the drafter shall not apply to this License. + </para> + + <para> + 12. RESPONSIBILITY FOR CLAIMS. As between Initial Developer and + the Contributors, each party is responsible for claims and + damages arising, directly or indirectly, out of its utilization + of rights under this License and You agree to work with Initial + Developer and Contributors to distribute such responsibility on + an equitable basis. Nothing herein is intended or shall be + deemed to constitute any admission of liability. + </para> + + <para> + 13. MULTIPLE-LICENSED CODE. Initial Developer may designate + portions of the Covered Code as "Multiple-Licensed". + "Multiple-Licensed" means that the Initial Developer permits you + to utilize portions of the Covered Code under Your choice of the + NPL or the alternative licenses, if any, specified by the + Initial Developer in the file described in Exhibit A. + </para> + + <para> + EXHIBIT A -Mozilla Public License. + </para> + + <para> + ``The contents of this file are subject to the Mozilla Public + License Version 1.1 (the "License"); you may not use this file + except in compliance with the License. You may obtain a copy of + the License at http://www.mozilla.org/MPL/ + </para> + + <para> + Software distributed under the License is distributed on an "AS + IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or + implied. See the License for the specific language governing + rights and limitations under the License. + </para> + + <para> + The Original Code is ______________________________________. + </para> + + <para> + The Initial Developer of the Original Code is + ________________________. Portions created by + ______________________ are Copyright (C) ______ + _______________________. All Rights Reserved. + </para> + + <para> + Contributor(s): ______________________________________. + </para> + + <para> + Alternatively, the contents of this file may be used under the + terms of the _____ license (the "[___] License"), in which case + the provisions of [______] License are applicable instead of + those above. If you wish to allow use of your version of this + file only under the terms of the [____] License and not to allow + others to use your version of this file under the MPL, indicate + your decision by deleting the provisions above and replace them + with the notice and other provisions required by the [___] + License. If you do not delete the provisions above, a recipient + may use your version of this file under either the MPL or the + [___] License." + </para> + + <para> + [NOTE: The text of this Exhibit A may differ slightly from the + text of the notices in the Source Code files of the Original + Code. You should use the text of this Exhibit A rather than the + text found in the Original Code Source Code for Your + Modifications.] + </para> + + </sect2> + + <sect2 id="licMIT"> + + <title>MIT License</title> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT + HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, + WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR + OTHER DEALINGS IN THE SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX11"> + + <title>X Consortium License (X11) (variant 1)</title> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT + HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, + WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR + OTHER DEALINGS IN THE SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX11-v2"> + + <title>X Consortium License (X11) (variant 2)</title> + + <para> + Copyright (c) 1987, 1989-1990, 1992-1995 X Consortium + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE + FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. + </para> + + <para> + Except as contained in this notice, the name of the X Consortium + shall not be used in advertising or otherwise to promote the + sale, use or other dealings in this Software without prior + written authorization from the X Consortium. + </para> + + </sect2> + + <sect2 id="licZLIB"> + + <title>zlib License</title> + + <para> + This software is provided 'as-is', without any express or + implied warranty. In no event will the authors be held liable + for any damages arising from the use of this software. + </para> + + <para> + Permission is granted to anyone to use this software for any + purpose, including commercial applications, and to alter it and + redistribute it freely, subject to the following restrictions: + </para> + + <para> + 1. The origin of this software must not be misrepresented; you + must not claim that you wrote the original software. If you use + this software in a product, an acknowledgment in the product + documentation would be appreciated but is not required. + </para> + + <para> + 2. Altered source versions must be plainly marked as such, and + must not be misrepresented as being the original software. + </para> + + <para> + 3. This notice may not be removed or altered from any source + distribution. + </para> + +<screen>Jean-loup Gailly Mark Adler +jloup@gzip.org madler@alumni.caltech.edu</screen> + + </sect2> + + <sect2 id="licApache"> + + <title>Apache License v2</title> + + <para> + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + </para> + + <para> + 1. Definitions. + </para> + + <para> + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + </para> + + <para> + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + </para> + + <para> + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + </para> + + <para> + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + </para> + + <para> + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + </para> + + <para> + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + </para> + + <para> + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + </para> + + <para> + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + </para> + + <para> + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + </para> + + <para> + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + </para> + + <para> + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + </para> + + <para> + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + </para> + + <para> + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + </para> + + <para> + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + </para> + + <para> + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + </para> + + <para> + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + </para> + + <para> + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + </para> + + <para> + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + </para> + + <para> + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + </para> + + <para> + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + </para> + + <para> + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + </para> + + <para> + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + </para> + + <para> + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + </para> + + <para> + END OF TERMS AND CONDITIONS + </para> + + </sect2> + + <sect2 id="licSSL"> + + <title>OpenSSL License</title> + + <para> + This package is an SSL implementation written by Eric Young + (eay@cryptsoft.com). The implementation was written so as to + conform with Netscape's SSL. + </para> + + <para> + This library is free for commercial and non-commercial use as + long as the following conditions are adhered to. The following + conditions apply to all code found in this distribution, be it + the RC4, RSA, lhash, DES, etc., code; not just the SSL code. The + SSL documentation included with this distribution is covered by + the same copyright terms except that the holder is Tim Hudson + (tjh@cryptsoft.com). + </para> + + <para> + Copyright remains Eric Young's, and as such any Copyright + notices in the code are not to be removed. If this package is + used in a product, Eric Young should be given attribution as the + author of the parts of the library used. This can be in the form + of a textual message at program startup or in documentation + (online or textual) provided with the package. + </para> + + <para> + Redistribution and use in source and binary forms, with or + without modification, are permitted provided that the following + conditions are met: + </para> + + <para> + 1. Redistributions of source code must retain the copyright + notice, this list of conditions and the following disclaimer. + </para> + + <para> + 2. Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + </para> + + <para> + 3. All advertising materials mentioning features or use of this + software must display the following acknowledgement: "This + product includes cryptographic software written by Eric Young + (eay@cryptsoft.com)" The word 'cryptographic' can be left out if + the routines from the library being used are not cryptographic + related :-). + </para> + + <para> + 4. If you include any Windows specific code (or a derivative + thereof) from the apps directory (application code) you must + include an acknowledgement: "This product includes software + written by Tim Hudson (tjh@cryptsoft.com)" + </para> + + <para> + THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND ANY + EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, + THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A + PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR + OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED + AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING + IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF + THE POSSIBILITY OF SUCH DAMAGE. + </para> + + <para> + The licence and distribution terms for any publicly available + version or derivative of this code cannot be changed. i.e. this + code cannot simply be copied and put under another distribution + licence [including the GNU Public Licence.] + </para> + + </sect2> + + <sect2 id="licSlirp"> + + <title>Slirp License</title> + + <para> + Copyright (c) 1995,1996 Danny Gasparovski. All rights reserved. + </para> + + <para> + Redistribution and use in source and binary forms, with or + without modification, are permitted provided that the following + conditions are met: + </para> + + <para> + 1. Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. + </para> + + <para> + 2. Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + </para> + + <para> + 3. Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + </para> + + <para> + THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED + WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED + WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL DANNY GASPAROVSKI OR + CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED + AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING + IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF + THE POSSIBILITY OF SUCH DAMAGE. + </para> + + </sect2> + + <sect2 id="licLZF"> + + <title>liblzf License</title> + + <para> + Redistribution and use in source and binary forms, with or + without modification, are permitted provided that the following + conditions are met: + </para> + + <para> + 1. Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. + </para> + + <para> + 2. Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + </para> + + <para> + 3. The name of the author may not be used to endorse or promote + products derived from this software without specific prior + written permission. + </para> + + <para> + THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY + EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, + THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A + PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR + BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED + TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING + IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF + THE POSSIBILITY OF SUCH DAMAGE. + </para> + + </sect2> + + <sect2 id="liclibping"> + + <title>libpng License</title> + + <para> + The PNG Reference Library is supplied "AS IS". The Contributing + Authors and Group 42, Inc. disclaim all warranties, expressed or + implied, including, without limitation, the warranties of + merchantability and of fitness for any purpose. The Contributing + Authors and Group 42, Inc. assume no liability for direct, + indirect, incidental, special, exemplary, or consequential + damages, which may result from the use of the PNG Reference + Library, even if advised of the possibility of such damage. + </para> + + <para> + Permission is hereby granted to use, copy, modify, and + distribute this source code, or portions hereof, for any + purpose, without fee, subject to the following restrictions: + </para> + + <para> + 1. The origin of this source code must not be misrepresented. + </para> + + <para> + 2. Altered versions must be plainly marked as such and must not + be misrepresented as being the original source. + </para> + + <para> + 3. This Copyright notice may not be removed or altered from any + source or altered source distribution. + </para> + + <para> + The Contributing Authors and Group 42, Inc. specifically permit, + without fee, and encourage the use of this source code as a + component to supporting the PNG file format in commercial + products. If you use this source code in a product, + acknowledgment is not required but would be appreciated. + </para> + + </sect2> + + <sect2 id="licLWIP"> + + <title>lwIP License</title> + + <para> + Redistribution and use in source and binary forms, with or + without modification, are permitted provided that the following + conditions are met: + </para> + + <para> + 1. Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. + </para> + + <para> + 2. Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + </para> + + <para> + 3. The name of the author may not be used to endorse or promote + products derived from this software without specific prior + written permission. + </para> + + <para> + THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY + EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, + THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A + PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR + BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED + TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING + IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF + THE POSSIBILITY OF SUCH DAMAGE. + </para> + + </sect2> + + <sect2 id="licLibXML"> + + <title>libxml License</title> + + <para> + Except where otherwise noted in the source code (e.g. the files + hash.c, list.c and the trio files, which are covered by a + similar licence but with different Copyright notices) all the + files are: + </para> + + <para> + Copyright (C) 1998-2012 Daniel Veillard. All Rights Reserved. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE DANIEL VEILLARD BE LIABLE + FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. + </para> + + <para> + Except as contained in this notice, the name of Daniel Veillard + shall not be used in advertising or otherwise to promote the + sale, use or other dealings in this Software without prior + written authorization from him. + </para> + + <para> + The file hash.c is: + </para> + + <para> + Copyright (C) 2000,2012 Bjorn Reese and Daniel Veillard. + </para> + + <para> + The file list.c is: + </para> + + <para> + Copyright (C) 2000 Gary Pennington and Daniel Veillard + </para> + + <para> + The trio files are: + </para> + + <para> + Copyright (C) 1998 Bjorn Reese and Daniel Stenberg. + </para> + + <para> + The license for hash.c, list.c, and the trio files is: + </para> + + <para> + Permission to use, copy, modify, and distribute this software + for any purpose with or without fee is hereby granted, provided + that the above copyright notice and this permission notice + appear in all copies. + </para> + + <para> + THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED + WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE. THE AUTHORS AND CONTRIBUTORS ACCEPT NO RESPONSIBILITY + IN ANY CONCEIVABLE MANNER. + </para> + + </sect2> + + <sect2 id="licgSOAP"> + + <title>gSOAP Public License Version 1.3a</title> + + <para> + The gSOAP public license is derived from the Mozilla Public + License (MPL1.1). The sections that were deleted from the + original MPL1.1 text are 1.0.1, 2.1.(c),(d), 2.2.(c),(d), + 8.2.(b), 10, and 11. Section 3.8 was added. The modified + sections are 2.1.(b), 2.2.(b), 3.2 (simplified), 3.5 (deleted + the last sentence), and 3.6 (simplified). + </para> + + <para> + 1 DEFINITIONS + </para> + + <para> + 1.1. "Contributor" means each entity that creates or contributes + to the creation of Modifications. + </para> + + <para> + 1.2. "Contributor Version" means the combination of the Original + Code, prior Modifications used by a Contributor, and the + Modifications made by that particular Contributor. + </para> + + <para> + 1.3. "Covered Code" means the Original Code, or Modifications or + the combination of the Original Code, and Modifications, in each + case including portions thereof. + </para> + + <para> + 1.4. "Electronic Distribution Mechanism" means a mechanism + generally accepted in the software development community for the + electronic transfer of data. + </para> + + <para> + 1.5. "Executable" means Covered Code in any form other than + Source Code. + </para> + + <para> + 1.6. "Initial Developer" means the individual or entity + identified as the Initial Developer in the Source Code notice + required by Exhibit A. + </para> + + <para> + 1.7. "Larger Work" means a work which combines Covered Code or + portions thereof with code not governed by the terms of this + License. + </para> + + <para> + 1.8. "License" means this document. + </para> + + <para> + 1.8.1. "Licensable" means having the right to grant, to the + maximum extent possible, whether at the time of the initial + grant or subsequently acquired, any and all of the rights + conveyed herein. + </para> + + <para> + 1.9. "Modifications" means any addition to or deletion from the + substance or structure of either the Original Code or any + previous Modifications. When Covered Code is released as a + series of files, a Modification is: + </para> + + <para> + A. Any addition to or deletion from the contents of a file + containing Original Code or previous Modifications. + </para> + + <para> + B. Any new file that contains any part of the Original Code, or + previous Modifications. + </para> + + <para> + 1.10. "Original Code" means Source Code of computer software + code which is described in the Source Code notice required by + Exhibit A as Original Code, and which, at the time of its + release under this License is not already Covered Code governed + by this License. + </para> + + <para> + 1.10.1. "Patent Claims" means any patent claim(s), now owned or + hereafter acquired, including without limitation, method, + process, and apparatus claims, in any patent Licensable by + grantor. + </para> + + <para> + 1.11. "Source Code" means the preferred form of the Covered Code + for making modifications to it, including all modules it + contains, plus any associated interface definition files, + scripts used to control compilation and installation of an + Executable, or source code differential comparisons against + either the Original Code or another well known, available + Covered Code of the Contributor's choice. The Source Code can be + in a compressed or archival form, provided the appropriate + decompression or de-archiving software is widely available for + no charge. + </para> + + <para> + 1.12. "You" (or "Your") means an individual or a legal entity + exercising rights under, and complying with all of the terms of, + this License or a future version of this License issued under + Section 6.1. For legal entities, "You" includes any entity which + controls, is controlled by, or is under common control with You. + For purposes of this definition, "control" means (a) the power, + direct or indirect, to cause the direction or management of such + entity, whether by contract or otherwise, or (b) ownership of + more than fifty percent (50%) of the outstanding shares or + beneficial ownership of such entity. + </para> + + <para> + 2 SOURCE CODE LICENSE. + </para> + + <para> + 2.1. The Initial Developer Grant. + </para> + + <para> + The Initial Developer hereby grants You a world-wide, + royalty-free, non-exclusive license, subject to third party + intellectual property claims: + </para> + + <para> + (a) under intellectual property rights (other than patent or + trademark) Licensable by Initial Developer to use, reproduce, + modify, display, perform, sublicense and distribute the Original + Code (or portions thereof) with or without Modifications, and/or + as part of a Larger Work; and + </para> + + <para> + (b) under patents now or hereafter owned or controlled by + Initial Developer, to make, have made, use and sell ("offer to + sell and import") the Original Code, Modifications, or portions + thereof, but solely to the extent that any such patent is + reasonably necessary to enable You to utilize, alone or in + combination with other software, the Original Code, + Modifications, or any combination or portions thereof. + </para> + + <para> + (c) + </para> + + <para> + (d) + </para> + + <para> + 2.2. Contributor Grant. + </para> + + <para> + Subject to third party intellectual property claims, each + Contributor hereby grants You a world-wide, royalty-free, + non-exclusive license + </para> + + <para> + (a) under intellectual property rights (other than patent or + trademark) Licensable by Contributor, to use, reproduce, modify, + display, perform, sublicense and distribute the Modifications + created by such Contributor (or portions thereof) either on an + unmodified basis, with other Modifications, as Covered Code + and/or as part of a Larger Work; and + </para> + + <para> + (b) under patents now or hereafter owned or controlled by + Contributor, to make, have made, use and sell ("offer to sell + and import") the Contributor Version (or portions thereof), but + solely to the extent that any such patent is reasonably + necessary to enable You to utilize, alone or in combination with + other software, the Contributor Version (or portions thereof). + </para> + + <para> + (c) + </para> + + <para> + (d) + </para> + + <para> + 3 DISTRIBUTION OBLIGATIONS. + </para> + + <para> + 3.1. Application of License. + </para> + + <para> + The Modifications which You create or to which You contribute + are governed by the terms of this License, including without + limitation Section 2.2. The Source Code version of Covered Code + may be distributed only under the terms of this License or a + future version of this License released under Section 6.1, and + You must include a copy of this License with every copy of the + Source Code You distribute. You may not offer or impose any + terms on any Source Code version that alters or restricts the + applicable version of this License or the recipients' rights + hereunder. However, You may include an additional document + offering the additional rights described in Section 3.5. + </para> + + <para> + 3.2. Availability of Source Code. + </para> + + <para> + Any Modification created by You will be provided to the Initial + Developer in Source Code form and are subject to the terms of + the License. 3.3. Description of Modifications. + </para> + + <para> + You must cause all Covered Code to which You contribute to + contain a file documenting the changes You made to create that + Covered Code and the date of any change. You must include a + prominent statement that the Modification is derived, directly + or indirectly, from Original Code provided by the Initial + Developer and including the name of the Initial Developer in (a) + the Source Code, and (b) in any notice in an Executable version + or related documentation in which You describe the origin or + ownership of the Covered Code. + </para> + + <para> + 3.4. Intellectual Property Matters. + </para> + + <para> + (a) Third Party Claims. If Contributor has knowledge that a + license under a third party's intellectual property rights is + required to exercise the rights granted by such Contributor + under Sections 2.1 or 2.2, Contributor must include a text file + with the Source Code distribution titled "LEGAL" which describes + the claim and the party making the claim in sufficient detail + that a recipient will know whom to contact. If Contributor + obtains such knowledge after the Modification is made available + as described in Section 3.2, Contributor shall promptly modify + the LEGAL file in all copies Contributor makes available + thereafter and shall take other steps (such as notifying + appropriate mailing lists or newsgroups) reasonably calculated + to inform those who received the Covered Code that new knowledge + has been obtained. + </para> + + <para> + (b) Contributor APIs. If Contributor's Modifications include an + application programming interface and Contributor has knowledge + of patent licenses which are reasonably necessary to implement + that API, Contributor must also include this information in the + LEGAL file. + </para> + + <para> + (c) Representations. Contributor represents that, except as + disclosed pursuant to Section 3.4(a) above, Contributor believes + that Contributor's Modifications are Contributor's original + creation(s) and/or Contributor has sufficient rights to grant + the rights conveyed by this License. + </para> + + <para> + 3.5. Required Notices. You must duplicate the notice in Exhibit + A in each file of the Source Code. If it is not possible to put + such notice in a particular Source Code file due to its + structure, then You must include such notice in a location (such + as a relevant directory) where a user would be likely to look + for such a notice. If You created one or more Modification(s) + You may add your name as a Contributor to the notice described + in Exhibit A. You must also duplicate this License in any + documentation for the Source Code where You describe recipients' + rights or ownership rights relating to Covered Code. You may + choose to offer, and to charge a fee for, warranty, support, + indemnity or liability obligations to one or more recipients of + Covered Code. However, You may do so only on Your own behalf, + and not on behalf of the Initial Developer or any Contributor. + </para> + + <para> + 3.6. Distribution of Executable Versions. You may distribute + Covered Code in Executable form only if the requirements of + Section 3.1-3.5 have been met for that Covered Code. You may + distribute the Executable version of Covered Code or ownership + rights under a license of Your choice, which may contain terms + different from this License, provided that You are in compliance + with the terms of this License and that the license for the + Executable version does not attempt to limit or alter the + recipient's rights in the Source Code version from the rights + set forth in this License. If You distribute the Executable + version under a different license You must make it absolutely + clear that any terms which differ from this License are offered + by You alone, not by the Initial Developer or any Contributor. + If you distribute executable versions containing Covered Code as + part of a product, you must reproduce the notice in Exhibit B in + the documentation and/or other materials provided with the + product. + </para> + + <para> + 3.7. Larger Works. You may create a Larger Work by combining + Covered Code with other code not governed by the terms of this + License and distribute the Larger Work as a single product. In + such a case, You must make sure the requirements of this License + are fulfilled for the Covered Code. + </para> + + <para> + 3.8. Restrictions. You may not remove any product + identification, copyright, proprietary notices or labels from + gSOAP. + </para> + + <para> + 4 INABILITY TO COMPLY DUE TO STATUTE OR REGULATION. + </para> + + <para> + If it is impossible for You to comply with any of the terms of + this License with respect to some or all of the Covered Code due + to statute, judicial order, or regulation then You must: (a) + comply with the terms of this License to the maximum extent + possible; and (b) describe the limitations and the code they + affect. Such description must be included in the LEGAL file + described in Section 3.4 and must be included with all + distributions of the Source Code. Except to the extent + prohibited by statute or regulation, such description must be + sufficiently detailed for a recipient of ordinary skill to be + able to understand it. + </para> + + <para> + 5 APPLICATION OF THIS LICENSE. + </para> + + <para> + This License applies to code to which the Initial Developer has + attached the notice in Exhibit A and to related Covered Code. + </para> + + <para> + 6 VERSIONS OF THE LICENSE. + </para> + + <para> + 6.1. New Versions. + </para> + + <para> + Grantor may publish revised and/or new versions of the License + from time to time. Each version will be given a distinguishing + version number. + </para> + + <para> + 6.2. Effect of New Versions. + </para> + + <para> + Once Covered Code has been published under a particular version + of the License, You may always continue to use it under the + terms of that version. You may also choose to use such Covered + Code under the terms of any subsequent version of the License. + </para> + + <para> + 6.3. Derivative Works. + </para> + + <para> + If You create or use a modified version of this License (which + you may only do in order to apply it to code which is not + already Covered Code governed by this License), You must (a) + rename Your license so that the phrase "gSOAP" or any + confusingly similar phrase do not appear in your license (except + to note that your license differs from this License) and (b) + otherwise make it clear that Your version of the license + contains terms which differ from the gSOAP Public License. + (Filling in the name of the Initial Developer, Original Code or + Contributor in the notice described in Exhibit A shall not of + themselves be deemed to be modifications of this License.) + </para> + + <para> + 7 DISCLAIMER OF WARRANTY. + </para> + + <para> + COVERED CODE IS PROVIDED UNDER THIS LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTY OF ANY KIND, WHETHER EXPRESS, IMPLIED OR + STATUTORY, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES + OF MERCHANTABILITY, OF FITNESS FOR A PARTICULAR PURPOSE, + NONINFRINGEMENT OF THIRD PARTY INTELLECTUAL PROPERTY RIGHTS, AND + ANY WARRANTY THAT MAY ARISE BY REASON OF TRADE USAGE, CUSTOM, OR + COURSE OF DEALING. WITHOUT LIMITING THE FOREGOING, YOU + ACKNOWLEDGE THAT THE SOFTWARE IS PROVIDED "AS IS" AND THAT THE + AUTHORS DO NOT WARRANT THE SOFTWARE WILL RUN UNINTERRUPTED OR + ERROR FREE. LIMITED LIABILITY THE ENTIRE RISK AS TO RESULTS AND + PERFORMANCE OF THE SOFTWARE IS ASSUMED BY YOU. UNDER NO + CIRCUMSTANCES WILL THE AUTHORS BE LIABLE FOR ANY SPECIAL, + INDIRECT, INCIDENTAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES OF ANY + KIND OR NATURE WHATSOEVER, WHETHER BASED ON CONTRACT, WARRANTY, + TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, + ARISING OUT OF OR IN ANY WAY RELATED TO THE SOFTWARE, EVEN IF + THE AUTHORS HAVE BEEN ADVISED ON THE POSSIBILITY OF SUCH DAMAGE + OR IF SUCH DAMAGE COULD HAVE BEEN REASONABLY FORESEEN, AND + NOTWITHSTANDING ANY FAILURE OF ESSENTIAL PURPOSE OF ANY + EXCLUSIVE REMEDY PROVIDED. SUCH LIMITATION ON DAMAGES INCLUDES, + BUT IS NOT LIMITED TO, DAMAGES FOR LOSS OF GOODWILL, LOST + PROFITS, LOSS OF DATA OR SOFTWARE, WORK STOPPAGE, COMPUTER + FAILURE OR MALFUNCTION OR IMPAIRMENT OF OTHER GOODS. IN NO EVENT + WILL THE AUTHORS BE LIABLE FOR THE COSTS OF PROCUREMENT OF + SUBSTITUTE SOFTWARE OR SERVICES. YOU ACKNOWLEDGE THAT THIS + SOFTWARE IS NOT DESIGNED FOR USE IN ON-LINE EQUIPMENT IN + HAZARDOUS ENVIRONMENTS SUCH AS OPERATION OF NUCLEAR FACILITIES, + AIRCRAFT NAVIGATION OR CONTROL, OR LIFE-CRITICAL APPLICATIONS. + THE AUTHORS EXPRESSLY DISCLAIM ANY LIABILITY RESULTING FROM USE + OF THE SOFTWARE IN ANY SUCH ON-LINE EQUIPMENT IN HAZARDOUS + ENVIRONMENTS AND ACCEPTS NO LIABILITY IN RESPECT OF ANY ACTIONS + OR CLAIMS BASED ON THE USE OF THE SOFTWARE IN ANY SUCH ON-LINE + EQUIPMENT IN HAZARDOUS ENVIRONMENTS BY YOU. FOR PURPOSES OF THIS + PARAGRAPH, THE TERM "LIFE-CRITICAL APPLICATION" MEANS AN + APPLICATION IN WHICH THE FUNCTIONING OR MALFUNCTIONING OF THE + SOFTWARE MAY RESULT DIRECTLY OR INDIRECTLY IN PHYSICAL INJURY OR + LOSS OF HUMAN LIFE. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN + ESSENTIAL PART OF THIS LICENSE. NO USE OF ANY COVERED CODE IS + AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER. + </para> + + <para> + 8 TERMINATION. + </para> + + <para> + 8.1. + </para> + + <para> + This License and the rights granted hereunder will terminate + automatically if You fail to comply with terms herein and fail + to cure such breach within 30 days of becoming aware of the + breach. All sublicenses to the Covered Code which are properly + granted shall survive any termination of this License. + Provisions which, by their nature, must remain in effect beyond + the termination of this License shall survive. + </para> + + <para> + 8.2. + </para> + + <para> + 8.3. + </para> + + <para> + If You assert a patent infringement claim against Participant + alleging that such Participant's Contributor Version directly or + indirectly infringes any patent where such claim is resolved + (such as by license or settlement) prior to the initiation of + patent infringement litigation, then the reasonable value of the + licenses granted by such Participant under Sections 2.1 or 2.2 + shall be taken into account in determining the amount or value + of any payment or license. + </para> + + <para> + 8.4. In the event of termination under Sections 8.1 or 8.2 + above, all end user license agreements (excluding distributors + and resellers) which have been validly granted by You or any + distributor hereunder prior to termination shall survive + termination. + </para> + + <para> + 9 LIMITATION OF LIABILITY. + </para> + + <para> + UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER TORT + (INCLUDING NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL YOU, THE + INITIAL DEVELOPER, ANY OTHER CONTRIBUTOR, OR ANY DISTRIBUTOR OF + COVERED CODE, OR ANY SUPPLIER OF ANY OF SUCH PARTIES, BE LIABLE + TO ANY PERSON FOR ANY INDIRECT, SPECIAL, INCIDENTAL, OR + CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT + LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, + COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER COMMERCIAL + DAMAGES OR LOSSES, EVEN IF SUCH PARTY SHALL HAVE BEEN INFORMED + OF THE POSSIBILITY OF SUCH DAMAGES. THIS LIMITATION OF LIABILITY + SHALL NOT APPLY TO LIABILITY FOR DEATH OR PERSONAL INJURY + RESULTING FROM SUCH PARTY'S NEGLIGENCE TO THE EXTENT APPLICABLE + LAW PROHIBITS SUCH LIMITATION. SOME JURISDICTIONS DO NOT ALLOW + THE EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL + DAMAGES, SO THIS EXCLUSION AND LIMITATION MAY NOT APPLY TO YOU. + </para> + + <para> + 10 U.S. GOVERNMENT END USERS. + </para> + + <para> + 11 MISCELLANEOUS. + </para> + + <para> + 12 RESPONSIBILITY FOR CLAIMS. + </para> + + <para> + As between Initial Developer and the Contributors, each party is + responsible for claims and damages arising, directly or + indirectly, out of its utilization of rights under this License + and You agree to work with Initial Developer and Contributors to + distribute such responsibility on an equitable basis. Nothing + herein is intended or shall be deemed to constitute any + admission of liability. + </para> + + <para> + EXHIBIT A. + </para> + + <para> + "The contents of this file are subject to the gSOAP Public + License Version 1.3 (the "License"); you may not use this file + except in compliance with the License. You may obtain a copy of + the License at + <ulink url="http://www.cs.fsu.edu/~engelen/soaplicense.html" />. + Software distributed under the License is distributed on an "AS + IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or + implied. See the License for the specific language governing + rights and limitations under the License. + </para> + + <para> + The Original Code of the gSOAP Software is: stdsoap.h, + stdsoap2.h, stdsoap.c, stdsoap2.c, stdsoap.cpp, stdsoap2.cpp, + soapcpp2.h, soapcpp2.c, soapcpp2_lex.l, soapcpp2_yacc.y, + error2.h, error2.c, symbol2.c, init2.c, soapdoc2.html, and + soapdoc2.pdf, httpget.h, httpget.c, stl.h, stldeque.h, + stllist.h, stlvector.h, stlset.h. + </para> + + <para> + The Initial Developer of the Original Code is Robert A. van + Engelen. Portions created by Robert A. van Engelen are Copyright + (C) 2001-2004 Robert A. van Engelen, Genivia inc. All Rights + Reserved. + </para> + + <para> + Contributor(s): "________________________." [Note: The text of + this Exhibit A may differ slightly form the text of the notices + in the Source Code files of the Original code. You should use + the text of this Exhibit A rather than the text found in the + Original Code Source Code for Your Modifications.] + </para> + + <para> + EXHIBIT B. + </para> + + <para> + "Part of the software embedded in this product is gSOAP + software. Portions created by gSOAP are Copyright (C) 2001-2004 + Robert A. van Engelen, Genivia inc. All Rights Reserved. THE + SOFTWARE IN THIS PRODUCT WAS IN PART PROVIDED BY GENIVIA INC AND + ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED + TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A + PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR + BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED + TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING + IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF + THE POSSIBILITY OF SUCH DAMAGE." + </para> + + </sect2> + + <sect2 id="licLibCurl"> + + <title>curl License</title> + + <para> + COPYRIGHT AND PERMISSION NOTICE + </para> + + <para> + Copyright (c) 1996 - 2009, Daniel Stenberg, daniel@haxx.se. + </para> + + <para> + All rights reserved. + </para> + + <para> + Permission to use, copy, modify, and distribute this software + for any purpose with or without fee is hereby granted, provided + that the above copyright notice and this permission notice + appear in all copies. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR + OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE + SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + </para> + + <para> + Except as contained in this notice, the name of a copyright + holder shall not be used in advertising or otherwise to promote + the sale, use or other dealings in this Software without prior + written authorization of the copyright holder. + </para> + + </sect2> + + <sect2 id="licLibgd"> + + <title>libgd License</title> + + <para> + Credits and license terms: + </para> + + <para> + In order to resolve any possible confusion regarding the + authorship of gd, the following copyright statement covers all + of the authors who have required such a statement. If you are + aware of any oversights in this copyright notice, please contact + Pierre-A. Joye who will be pleased to correct them. + </para> + + <para> + Portions copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, + 2001, 2002, 2003, 2004 by Cold Spring Harbor Laboratory. Funded + under Grant P41-RR02188 by the National Institutes of Health. + </para> + + <para> + Portions copyright 1996, 1997, 1998, 1999, 2000, 2001, 2002, + 2003, 2004 by Boutell.Com, Inc. + </para> + + <para> + Portions relating to GD2 format copyright 1999, 2000, 2001, + 2002, 2003, 2004 Philip Warner. + </para> + + <para> + Portions relating to PNG copyright 1999, 2000, 2001, 2002, 2003, + 2004 Greg Roelofs. + </para> + + <para> + Portions relating to gdttf.c copyright 1999, 2000, 2001, 2002, + 2003, 2004 John Ellson (ellson@graphviz.org). + </para> + + <para> + Portions relating to gdft.c copyright 2001, 2002, 2003, 2004 + John Ellson (ellson@graphviz.org). + </para> + + <para> + Portions copyright 2000, 2001, 2002, 2003, 2004, 2005, 2006, + 2007, 2008 Pierre-Alain Joye (pierre@libgd.org). + </para> + + <para> + Portions relating to JPEG and to color quantization copyright + 2000, 2001, 2002, 2003, 2004, Doug Becker and copyright (C) + 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 + Thomas G. Lane. This software is based in part on the work of + the Independent JPEG Group. See the file README-JPEG.TXT for + more information. + </para> + + <para> + Portions relating to GIF compression copyright 1989 by Jef + Poskanzer and David Rowley, with modifications for thread safety + by Thomas Boutell. + </para> + + <para> + Portions relating to GIF decompression copyright 1990, 1991, + 1993 by David Koblas, with modifications for thread safety by + Thomas Boutell. + </para> + + <para> + Portions relating to WBMP copyright 2000, 2001, 2002, 2003, 2004 + Maurice Szmurlo and Johan Van den Brande. + </para> + + <para> + Portions relating to GIF animations copyright 2004 Jaakko + Hyvätti (jaakko.hyvatti@iki.fi) + </para> + + <para> + Permission has been granted to copy, distribute and modify gd in + any context without fee, including a commercial application, + provided that this notice is present in user-accessible + supporting documentation. + </para> + + <para> + This does not affect your ownership of the derived work itself, + and the intent is to assure proper credit for the authors of gd, + not to interfere with your productive use of gd. If you have + questions, ask. "Derived works" includes all programs that + utilize the library. Credit must be given in user-accessible + documentation. + </para> + + <para> + This software is provided "AS IS." The copyright holders + disclaim all warranties, either express or implied, including + but not limited to implied warranties of merchantability and + fitness for a particular purpose, with respect to this code and + accompanying documentation. + </para> + + <para> + Although their code does not appear in gd, the authors wish to + thank David Koblas, David Rowley, and Hutchison Avenue Software + Corporation for their prior contributions. + </para> + + </sect2> + + <sect2 id="licBsdIntel"> + + <title>BSD License from Intel</title> + + <para> + All rights reserved. + </para> + + <para> + Redistribution and use in source and binary forms, with or + without modification, are permitted provided that the following + conditions are met: + </para> + + <itemizedlist> + + <listitem> + <para> + Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. + </para> + </listitem> + + <listitem> + <para> + Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials + provided with the distribution. + </para> + </listitem> + + <listitem> + <para> + Neither the name of the Intel Corporation nor the names of + its contributors may be used to endorse or promote products + derived from this software without specific prior written + permission. + </para> + </listitem> + + </itemizedlist> + + <para> + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND + CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR + CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED + AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING + IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF + THE POSSIBILITY OF SUCH DAMAGE. + </para> + + </sect2> + + <sect2 id="licIJG"> + + <title>IJG (Independent JPEG Group) License</title> + + <para> + The authors make NO WARRANTY or representation, either express + or implied, with respect to this software, its quality, + accuracy, merchantability, or fitness for a particular purpose. + This software is provided "AS IS", and you, its user, assume the + entire risk as to its quality and accuracy. + </para> + + <para> + This software is copyright (C) 1991-2021, Thomas G. Lane, Guido + Vollbeding. All Rights Reserved except as specified below. + </para> + + <para> + Permission is hereby granted to use, copy, modify, and + distribute this software (or portions thereof) for any purpose, + without fee, subject to these conditions: + </para> + + <para> + (1) If any part of the source code for this software is + distributed, then this README file must be included, with this + copyright and no-warranty notice unaltered; and any additions, + deletions, or changes to the original files must be clearly + indicated in accompanying documentation. + </para> + + <para> + (2) If only executable code is distributed, then the + accompanying documentation must state that "this software is + based in part on the work of the Independent JPEG Group". + </para> + + <para> + (3) Permission for use of this software is granted only if the + user accepts full responsibility for any undesirable + consequences; the authors accept NO LIABILITY for damages of any + kind. + </para> + + <para> + These conditions apply to any software derived from or based on + the IJG code, not just to the unmodified library. If you use our + work, you ought to acknowledge us. + </para> + + <para> + Permission is NOT granted for the use of any IJG author's name + or company name in advertising or publicity relating to this + software or products derived from it. This software may be + referred to only as "the Independent JPEG Group's software". + </para> + + <para> + We specifically permit and encourage the use of this software as + the basis of commercial products, provided that all warranty or + liability claims are assumed by the product vendor. + </para> + + </sect2> + + <sect2 id="licBsdJPEG"> + + <title>libjpeg-turbo Modified (3-clause) BSD License</title> + + <para> + Copyright (C)2009-2022 D. R. Commander. All Rights Reserved. + Copyright (C)2015 Viktor Szathmáry. All Rights Reserved. + </para> + + <para> + Redistribution and use in source and binary forms, with or + without modification, are permitted provided that the following + conditions are met: + </para> + + <orderedlist> + + <listitem> + <para> + Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. + </para> + </listitem> + + <listitem> + <para> + Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials + provided with the distribution. + </para> + </listitem> + + <listitem> + <para> + Neither the name of the libjpeg-turbo Project nor the names + of its contributors may be used to endorse or promote + products derived from this software without specific prior + written permission. + </para> + </listitem> + + </orderedlist> + + <para> + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS", + AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE + LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + </para> + + </sect2> + + <sect2 id="licFreeBsd"> + + <title>FreeBSD License</title> + + <para> + The compilation of software known as FreeBSD is distributed + under the following terms: + </para> + + <para> + Copyright 1992-2022 The FreeBSD Project. + </para> + + <para> + Redistribution and use in source and binary forms, with or + without modification, are permitted provided that the following + conditions are met: + </para> + + <orderedlist> + + <listitem> + <para> + Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. + </para> + </listitem> + + <listitem> + <para> + Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials + provided with the distribution. + </para> + </listitem> + + </orderedlist> + + <para> + THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS + IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT + SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF + THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + SUCH DAMAGE. + </para> + + <para> + The views and conclusions contained in the software and + documentation are those of the authors and should not be + interpreted as representing official policies, either expressed + or implied, of the FreeBSD Project. + </para> + + </sect2> + + <sect2 id="licNetBsd"> + + <title>NetBSD License</title> + + <para> + Copyright (c) 2008 The NetBSD Foundation, Inc. + </para> + + <para> + This code is derived from software contributed to The NetBSD + Foundation by + </para> + + <para> + Redistribution and use in source and binary forms, with or + without modification, are permitted provided that the following + conditions are met: + </para> + + <orderedlist> + + <listitem> + <para> + Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. + </para> + </listitem> + + <listitem> + <para> + Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials + provided with the distribution. + </para> + </listitem> + + </orderedlist> + + <para> + THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND + CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS + BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED + TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + </para> + + </sect2> + + <sect2 id="licVPX"> + + <title>VPX License</title> + + <para> + Copyright (c) 2010, The WebM Project authors. All rights + reserved. + </para> + + <para> + Redistribution and use in source and binary forms, with or + without modification, are permitted provided that the following + conditions are met: + </para> + + <itemizedlist> + + <listitem> + <para> + Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. + </para> + </listitem> + + <listitem> + <para> + Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials + provided with the distribution. + </para> + </listitem> + + <listitem> + <para> + Neither the name of Google, nor the WebM Project, nor the + names of its contributors may be used to endorse or promote + products derived from this software without specific prior + written permission. + </para> + </listitem> + + </itemizedlist> + + <para> + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND + CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR + CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED + AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING + IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF + THE POSSIBILITY OF SUCH DAMAGE. + </para> + + </sect2> + + <sect2 id="licVorbis"> + + <title>Vorbis License</title> + + <para> + Copyright (c) 2002-2020 Xiph.org Foundation + </para> + + <para> + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + </para> + + <itemizedlist> + + <listitem> + <para> + Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. + </para> + </listitem> + + <listitem> + <para> + Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials + provided with the distribution. + </para> + </listitem> + + <listitem> + <para> + Neither the name of the Xiph.org Foundation nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + </para> + </listitem> + + </itemizedlist> + + <para> + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION + OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + </para> + + </sect2> + + <sect2 id="licCurl"> + + <title>curl License</title> + + <para> + Copyright (c) 1996 - 2022, Daniel Stenberg, + <daniel@haxx.se>, and many contributors, see the THANKS + file. + </para> + + <para> + All rights reserved. + </para> + + <para> + Permission to use, copy, modify, and distribute this software for + any purpose with or without fee is hereby granted, provided that + the above copyright notice and this permission notice appear in + all copies. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR + OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE + SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + </para> + + <para> + Except as contained in this notice, the name of a copyright + holder shall not be used in advertising or otherwise to promote + the sale, use or other dealings in this Software without prior + written authorization of the copyright holder. + </para> + + </sect2> + + <sect2 id="licDocBook-XML-DTD"> + + <title>DocBook XML DTD License</title> + + <para> + Copyright 1992-2004 HaL Computer Systems, Inc., O'Reilly + & Associates, Inc., ArborText, Inc., Fujitsu Software + Corporation, Norman Walsh, Sun Microsystems, Inc., and the + Organization for the Advancement of Structured Information + Standards (OASIS). + </para> + + <para> + See also http://docbook.org/specs/ + </para> + + <para> + $Id: user_ThirdParty.xml $ + </para> + + <para> + Permission to use, copy, modify and distribute the DocBook XML + DTD and its accompanying documentation for any purpose and + without fee is hereby granted in perpetuity, provided that the + above copyright notice and this paragraph appear in all copies. + The copyright holders make no representation about the + suitability of the DTD for any purpose. It is provided "as is" + without expressed or implied warranty. + </para> + + <para> + If you modify the DocBook DTD in any way, except for declaring + and referencing additional sets of general entities and + declaring additional notations, label your DTD as a variant of + DocBook. See the maintenance documentation for more information. + </para> + + <para> + Please direct all questions, bug reports, or suggestions for + changes to the docbook@lists.oasis-open.org mailing list. For + more information, see http://www.oasis-open.org/docbook/. + </para> + + </sect2> + + <sect2 id="licDocBook-XSL-SS"> + + <title>DocBook XSL Stylesheets License</title> + + <para> + Copyright (C) 1999, 2000, 2001, 2002 Norman Walsh + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the ``Software''), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <itemizedlist> + + <listitem> + <para> + The above copyright notice and this permission notice shall + be included in all copies or substantial portions of the + Software. + </para> + </listitem> + + <listitem> + <para> + Except as contained in this notice, the names of individuals + credited with contribution to this software shall not be used + in advertising or otherwise to promote the sale, use or other + dealings in this Software without prior written authorization + from the individuals in question. + </para> + </listitem> + + <listitem> + <para> + Any stylesheet derived from this Software that is publically + distributed will be identified with a different name and the + version strings in any derived Software will be changed so + that no possibility of confusion between the derived package + and this Software will exist. + </para> + </listitem> + + </itemizedlist> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL NORMAN WALSH OR ANY OTHER + CONTRIBUTOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, + WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR + OTHER DEALINGS IN THE SOFTWARE. + </para> + + <para> + These stylesheets are maintained by Norman Walsh, <ndw@nwalsh.com>. + </para> + + </sect2> + + <sect2 id="licIntel"> + + <title>Intel ACPI Component Architecture (ACPICA) License</title> + + <itemizedlist> + + <listitem> + <para> + 1. Copyright Notice + </para> + + <para> + Some or all of this work - Copyright (c) 1999 - 2017, Intel Corp. + All rights reserved. + </para> + </listitem> + + <listitem> + <para> + 2. License + </para> + + <itemizedlist> + + <listitem> + <para> + 2.1. This is your license from Intel Corp. under its + intellectual property rights. You may have additional + license terms from the party that provided you this + software, covering your right to use that party's + intellectual property rights. + </para> + </listitem> + + <listitem> + <para> + 2.2. Intel grants, free of charge, to any person + ("Licensee") obtaining a copy of the source code + appearing in this file ("Covered Code") an irrevocable, + perpetual, worldwide license under Intel's copyrights in + the base code distributed originally by Intel ("Original + Intel Code") to copy, make derivatives, distribute, use + and display any portion of the Covered Code in any form, + with the right to sublicense such rights; and + </para> + </listitem> + + <listitem> + <para> + 2.3. Intel grants Licensee a non-exclusive and + non-transferable patent license (with the right to + sublicense), under only those claims of Intel patents + that are infringed by the Original Intel Code, to make, + use, sell, offer to sell, and import the Covered Code + and derivative works thereof solely to the minimum + extent necessary to exercise the above copyright + license, and in no event shall the patent license + extend to any additions to or modifications of the + Original Intel Code. No other license or right is + granted directly or by implication, estoppel or + otherwise; + </para> + </listitem> + + </itemizedlist> + + </listitem> + + <listitem> + <para> + 3. Conditions + </para> + + <itemizedlist> + + <listitem> + <para> + 3.1. Redistribution of Source with Rights to Further + Distribute Source. Redistribution of source code of any + substantial portion of the Covered Code or modification + with rights to further distribute source must include + the above Copyright Notice, the above License, this + list of Conditions, and the following Disclaimer and + Export Compliance provision. In addition, Licensee must + cause all Covered Code to which Licensee contributes to + contain a file documenting the changes Licensee made to + create that Covered Code and the date of any change. + Licensee must include in that file the documentation of + any changes made by any predecessor Licensee. Licensee + must include a prominent statement that the + modification is derived, directly or indirectly, from + Original Intel Code. + </para> + </listitem> + + <listitem> + <para> + 3.2. Redistribution of Source with no Rights to Further + Distribute Source. Redistribution of source code of any + substantial portion of the Covered Code or modification + without rights to further distribute source must + include the following Disclaimer and Export Compliance + provision in the documentation and/or other materials + provided with distribution. In addition, Licensee may + not authorize further sublicense of source of any + portion of the Covered Code, and must include terms to + the effect that the license from Licensee to its + licensee is limited to the intellectual property + embodied in the software Licensee provides to its + licensee, and not to intellectual property embodied in + modifications its licensee may make. + </para> + </listitem> + + <listitem> + <para> + 3.3. Redistribution of Executable. Redistribution in + executable form of any substantial portion of the + Covered Code or modification must reproduce the above + Copyright Notice, and the following Disclaimer and + Export Compliance provision in the documentation and/or + other materials provided with the distribution. + </para> + </listitem> + + <listitem> + <para> + 3.4. Intel retains all right, title, and interest in and + to the Original Intel Code. + </para> + </listitem> + + <listitem> + <para> + 3.5. Neither the name Intel nor any other trademark owned + or controlled by Intel shall be used in advertising or + otherwise to promote the sale, use or other dealings in + products derived from or relating to the Covered Code + without prior written authorization from Intel. + </para> + </listitem> + + </itemizedlist> + + </listitem> + + <listitem> + <para> + 4. Disclaimer and Export Compliance + </para> + + <itemizedlist> + + <listitem> + <para> + 4.1. INTEL MAKES NO WARRANTY OF ANY KIND REGARDING ANY + SOFTWARE PROVIDED HERE. ANY SOFTWARE ORIGINATING FROM + INTEL OR DERIVED FROM INTEL SOFTWARE IS PROVIDED "AS IS," + AND INTEL WILL NOT PROVIDE ANY SUPPORT, ASSISTANCE, + INSTALLATION, TRAINING OR OTHER SERVICES. INTEL WILL NOT + PROVIDE ANY UPDATES, ENHANCEMENTS OR EXTENSIONS. INTEL + SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTIES OF + MERCHANTABILITY, NONINFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE. + </para> + </listitem> + + <listitem> + <para> + 4.2. IN NO EVENT SHALL INTEL HAVE ANY LIABILITY TO + LICENSEE, ITS LICENSEES OR ANY OTHER THIRD PARTY, FOR ANY + LOST PROFITS, LOST DATA, LOSS OF USE OR COSTS OF + PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, OR FOR ANY + INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF + THIS AGREEMENT, UNDER ANY CAUSE OF ACTION OR THEORY OF + LIABILITY, AND IRRESPECTIVE OF WHETHER INTEL HAS ADVANCE + NOTICE OF THE POSSIBILITY OF SUCH DAMAGES. THESE + LIMITATIONS SHALL APPLY NOTWITHSTANDING THE FAILURE OF + THE ESSENTIAL PURPOSE OF ANY LIMITED REMEDY. + </para> + </listitem> + + <listitem> + <para> + 4.3. Licensee shall not export, either directly or + indirectly, any of this software or system incorporating + such software without first obtaining any required + license or other approval from the U. S. Department of + Commerce or any other agency or department of the United + States Government. In the event Licensee exports any + such software from the United States or re-exports any + such software from a foreign destination, Licensee shall + ensure that the distribution and export/re-export of the + software is in compliance with all laws, regulations, + orders, or other restrictions of the U.S. Export + Administration Regulations. Licensee agrees that neither + it nor any of its subsidiaries will export/re-export any + technical data, process, software, or service, directly + or indirectly, to any country for which the United + States government or any agency thereof requires an + export license, other governmental approval, or letter + of assurance, without first obtaining such license, + approval or letter. + </para> + </listitem> + + </itemizedlist> + + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="licKhronos"> + + <title>Khronos License</title> + + <para> + Copyright (c) 2008-2018 The Khronos Group Inc. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and/or associated + documentation files (the "Materials"), to deal in the Materials + without restriction, including without limitation the rights to + use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Materials, and to permit persons to + whom the Materials are furnished to do so, subject to the + following conditions: + </para> + + <para> + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Materials. + </para> + + <para> + THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE + AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT + HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, + WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE MATERIALS OR THE USE OR + OTHER DEALINGS IN THE MATERIALS. + </para> + + </sect2> + + <sect2 id="licSGI-FSL-B"> + + <title>SGI Free Software License B</title> + + <para> + Copyright (C) 1991-2000 Silicon Graphics, Inc. All Rights Reserved. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice including the dates of first + publication and either this permission notice or a reference to + http://oss.sgi.com/projects/FreeB/ shall be included in all + copies or substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL SILICON GRAPHICS, INC. BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN + ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR + IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + THE SOFTWARE. + </para> + + <para> + Except as contained in this notice, the name of Silicon + Graphics, Inc. shall not be used in advertising or otherwise to + promote the sale, use or other dealings in this Software without + prior written authorization from Silicon Graphics, Inc. + </para> + + </sect2> + + <sect2 id="licBoost"> + + <title>Boost Software License</title> + + <para> + Boost Software License - Version 1.0 - August 17th, 2003 + </para> + + <para> + Permission is hereby granted, free of charge, to any person or + organization obtaining a copy of the software and accompanying + documentation covered by this license (the "Software") to use, + reproduce, display, distribute, execute, and transmit the + Software, and to prepare derivative works of the Software, and + to permit third-parties to whom the Software is furnished to do + so, all subject to the following: + </para> + + <itemizedlist> + + <listitem> + <para> + The copyright notices in the Software and this entire + statement, including the above license grant, this + restriction and the following disclaimer, must be included + in all copies of the Software, in whole or in part, and all + derivative works of the Software, unless such copies or + derivative works are solely in the form of + machine-executable object code generated by a source + language processor. + </para> + </listitem> + + </itemizedlist> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND + NON-INFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR + ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE FOR ANY DAMAGES OR + OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR + OTHER DEALINGS IN THE SOFTWARE. + </para> + + </sect2> + + <sect2 id="licMesa-default"> + + <title>Default Mesa 3D Graphics Library License</title> + + <para> + License / Copyright Information + </para> + + <para> + The Mesa distribution consists of several components. Different + copyrights and licenses apply to different components. For + example, the GLX client code uses the SGI Free Software License + B, and some of the Mesa device drivers are copyrighted by + their authors. See below for a list of Mesa's main components + and the license for each. + </para> + + <para> + The core Mesa library is licensed according to the terms of the + MIT license. This allows integration with the XFree86, Xorg and + DRI projects. + </para> + + <para> + The default Mesa license is as follows: + </para> + + <para> + Copyright (C) 1999-2007 Brian Paul All Rights Reserved. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A + PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, + DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF + CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR + IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + THE SOFTWARE. + </para> + + <para> + Attention, Contributors + </para> + + <para> + When contributing to the Mesa project you must agree to the + licensing terms of the component to which you're contributing. + The following section lists the primary components of the Mesa + distribution and their respective licenses. + </para> + + <para> + Mesa Component Licenses + </para> + + <table id="Mesa-component-licenses" tabstyle="oracle-all"> + <title>Mesa Component Licenses</title> + <tgroup cols="3" align="center"> + <thead> + <row> + <entry><para> + <emphasis role="bold">Component</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Location</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">License</emphasis> + </para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para> + Main Mesa code + </para></entry> + <entry><para> + <filename>src/mesa/</filename> + </para></entry> + <entry><para> + <xref linkend="licMIT"/> + </para></entry> + </row> + <row> + <entry><para> + Device drivers + </para></entry> + <entry><para> + <filename>src/mesa/drivers/*</filename> + </para></entry> + <entry><para> + <xref linkend="licMIT"/>, generally + </para></entry> + </row> + <row> + <entry><para> + Gallium code + </para></entry> + <entry><para> + <filename>src/gallium/</filename> + </para></entry> + <entry><para> + <xref linkend="licMIT"/> + </para></entry> + </row> + <row> + <entry><para> + Ext headers + </para></entry> + <entry><para> + <filename>include/GL/glext.h</filename> + <filename>include/GL/glxext.h</filename> + </para></entry> + <entry><para> + <xref linkend="licKhronos"/> + </para></entry> + </row> + <row> + <entry><para> + GLX client code + </para></entry> + <entry><para> + <filename>src/glx/</filename> + </para></entry> + <entry><para> + <xref linkend="licSGI-FSL-B"/> + </para></entry> + </row> + <row> + <entry><para> + C11 thread emulation + </para></entry> + <entry><para> + <filename>include/c11/threads*.h</filename> + </para></entry> + <entry><para> + <xref linkend="licBoost"/> (permissive) + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + Additional copyrights: + </para> + + <para> + Copyright (c) 2001, 2002, 2003, 2004 The SCons Foundation; + Copyright IBM Corporation 2003, 2004, 2005, 2006; Copyright Zack + Rusin 2005. All Rights Reserved.; Copyright John Maddock 2006.; + Copyright (c) 2002, 2007-2011 Apple Inc.; Copyright (c) 2006 - + 2015, 2017 Intel Corporation; Copyright (C) 2005 Aapo Tahkola.; + Copyright (C) 2014 Adrián Arroyo Calle + <adrian.arroyocalle@gmail.com>; Copyright (c) 2014 Alex + Henrie <alexhenrie24@gmail.com>; Copyright 2006-2012, + Haiku. All rights reserved.; Copyright (C) 2015 Android-x86 Open + Source Project; Copyright 2010 Thomas Balling Sørensen & Orasanu + Lucian.; Copyright (C) 2010 Belen Masia (bmasia@unizar.es); + Copyright (c) 2011 Benjamin Franzke; Copyright (c) 2015 Boyan + Ding; Copyright (c) 2014 Broadcom; Copyright (c) 2011 Bryan + Cain; Copyright (c) 2007 Carl Worth; Copyright (C) 2015 Chih-Wei + Huang <cwhuang@linux.org.tw>; Copyright (C) 2010, 2013 + Christoph Bumiller; Copyright 2011 The Chromium OS authors.; + Copyright (c) 2012 Collabora, Ltd.; Copyright (c) 2014 Connor + Abbott; Copyright (c) 2007-2010 Dan Nicholson; Copyright (c) + 2011 Daniel Richard G. <skunk@iSKUNK.ORG>; Copyright (c) + 2007 Dave Airlie <airlied@linux.ie>; Copyright (C) + 1999-2004 David Airlie All Rights Reserved.; Copyright 2015 + Axel Davy <axel.davy@ens.fr>; Copyright 2016 Nayan + Deshmukh.; Copyright (c) 2010 Diego Elio Petteno` + <flameeyes@gmail.com>; Copyright (c) 2017 Dylan Baker; + Copyright (c) 2011-2014 Emil Velikov + <emil.l.velikov@gmail.com>; Copyright (c) 2012-2013 + Etnaviv Project; Copyright (C) 2003 Felix Kuehling; Copyright + (C) 2010 Fernando Navarro (fernandn@microsoft.com); Copyright + 2008-2009 Jose Fonseca; Copyright (c) 2009 Francesco Salvestrini + <salvestrini@users.sourceforge.net>; Copyright (c) 2013 + Gabriele Svelto <gabriele.svelto@gmail.com>; Copyright (c) + 2017 Gert Wollny; Copyright 2015 Zoltan Gilian; Copyright 2012 + Vadim Girlin <vadimgirlin@gmail.com>; Copyright (c) 2017, + Google Inc.; Copyright 2013 Grigori Goronzy + <greg@chown.ath.cx>; Copyright (c) 2017 Gražvydas Ignotas; + Copyright (c) 2002 Greg Parker. All Rights Reserved.; Copyright + (c) 2013 Gregory Hainaut <gregory.hainaut@gmail.com>; + Copyright (c) 2008 Guido U. Draheim <guidod@gmx.de>; + Copyright (c) 2007-2008, 2014-2016 Red Hat, Inc.; Copyright + 2006-2008, Philippe Houdoin. All rights reserved.; Copyright (C) + 1998-2013 VMware, Inc. All rights reserved.; Copyright + 1998-1999 Precision Insight, Inc., Cedar Park, Texas.; Copyright + (c) 2007, 2010 Jakob Bornecrantz <wallbraker@gmail.com>; + Copyright (c) 2009 Jeremy Huddleston, Julien Cristau, and + Matthieu Herrb; Copyright (C) 2009, 2012 Francisco Jerez.; + Copyright (c) 2008, 2010 Jérôme Glisse + <glisse@freedesktop.org>; Copyright (c) 2008 John + Darrington <j.darrington@elvis.murdoch.edu.au>; Copyright + (c) 2009-2014 Jon TURNEY; Copyright (C) 2010 Jorge Jimenez + (jorge@iryoku.com); Copyright (C) 2010 Jose I. Echevarria + (joseignacioechevarria@gmail.com); Copyright (c) 2010-2014 + Christian König; Copyright (c) 2008-2011 Kristian Høgsberg; + Copyright 2011-2013 Maarten Lankhorst, Ilia Mirkin; Copyright + (c) 2012 Laurent Carlier <lordheavym@gmail.com>; Copyright + (C) 2011 Lauri Kasanen (cand@gmx.com); Copyright (C) 2016 + Linaro, Ltd, Rob Herring <robh@kernel.org>; Copyright + 2000, 2001 VA Linux Systems Inc., Fremont, California.; + Copyright (c) 2010 Luca Barbieri; Copyright (C) 2010, 2011 + LunarG Inc.; Copyright (c) 2011 Maarten Bosmans + <mkbosmans@gmail.com>; Copyright (c) 2008, 2009 Maciej + Cencora <m.cencora@gmail.com>; Copyright 2010 Younes + Manton & Thomas Balling Sørensen.; Copyright 2009 Younes + Manton.; Copyright 2014-2015 Serge Martin; Copyright (c) 2012 + Matt Turner <mattst88@gmail.com>; Copyright (c) 2016 Mauro + Rossi <issor.oruam@gmail.com>; Copyright (C) 2010, 2011 + Advanced Micro Devices, Inc.; Copyright (c) 2009-2010 Mikhail + Gusarov; Copyright (C) 2016 Miklós Máté; Copyright (C) 2013, + 2014, 2016 Ilia Mirkin. All Rights Reserved.; Copyright (C) 2011 + Morgan Armand <morgan.devel@gmail.com>; Copyright (C) + 2004, 2009 Nicolai Hähnle <nhaehnle@gmail.com>; Copyright + (c) 2016 Bas Nieuwenhuizen; Copyright (c) 2014, 2015, NVIDIA + Corporation; Copyright (c) 2009, 2010 Marek Olšák + <maraeo@gmail.com>; Copyright (c) 2009 Pauli Nieminen; + Copyright (c) 1999-2000 Pawel W. Olszta. All Rights Reserved.; + Copyright 2007 Nouveau Project; Copyright 2011 Adam Rak + <adam.rak@streamnovation.com>; Copyright (c) 2012 Rob + Clark <robclark@freedesktop.org>; Copyright (C) 2004 + Roland Scheidegger All Rights Reserved.; Copyright 2015 + Patrick Rudolph <siro@das-labor.org>; Copyright (C) 2015 + Samuel Pitoiset; Copyright 2008, 2010 George Sapountzis + <gsapountzis@gmail.com>; Copyright (c) 2014 Scott Mansell; + Copyright (C) 1991-2000 Silicon Graphics, Inc. All Rights + Reserved.; Copyright (c) 2008, 2009 Corbin Simpson + <MostAwesomeDude@gmail.com>; Copyright (c) 2009 Joakim + Sindholt <opensource@zhasha.com>; Copyright (C) 2005, 2008 + Ben Skeggs.; Copyright 2008 Dennis Smit; Copyright (c) + 2003-2005, Stefan Gustavson; Copyright (C) 2005 Stephane + Marchesin; Copyright (c) 2008 Steven G. Johnson + <stevenj@alum.mit.edu>; Copyright 2000, 2001 ATI + Technologies Inc., Ontario, Canada, and$ VA Linux Systems Inc., + Fremont, California.; Copyright 2000-2002 ATI Technologies Inc., + Ontario, Canada, and VMware, Inc.; Copyright (c) 2000 The NetBSD + Foundation, Inc.; Copyright (c) 2015 Thomas Helland; Copyright + (C) 1995 Thorsten.Ohl @ Physik.TH-Darmstadt.de; Copyright (C) + 2013, 2017 Timothy Arceri All Rights Reserved.; Copyright (c) + 2002 Todd C. Miller <Todd.Miller@courtesan.com>; Copyright + (c) 2010, 2012-2014 Tom Stellard <tstellar@gmail.com>; + Copyright (C) 2014 Tomasz Figa <tomasz.figa@gmail.com>; + Copyright (c) 2004 Torrey T. Lyons. All Rights Reserved.; + Copyright (c) 2003, 2007-2008 Tungsten Graphics, Inc., Cedar + Park, TX., USA; Copyright 1992 Vrije Universiteit, The + Netherlands; Copyright (c) 2015-2016 Valve Corporation; + Copyright 2014-2016 Jan Vesely; Copyright (c) 2012 Vincent + Lejeune; Copyright 2013 Alexander von Gluck IV + <kallisti5@unixzen.com>; Copyright (c) 2013 W.J. van der + Laan; Copyright (C) The Weather Channel, Inc. 2002. All Rights + Reserved.; Copyright (C) 1999 Wittawat Yamwong; Copyright + 2009-2010 Chia-I Wu <olvaffe@gmail.com>; Copyright (C) + 2009 Chia-I Wu <olv@0xlab.org>; Copyright 2009 Artur + Wyszynski <harakash@gmail.com>; Copyright (c) 2012 Yaakov + Selkowitz and Keith Packard; Copyright (c) 1988-2004 Keith + Packard and Bart Massey.; Copyright (C) 2016 Zodiac Inflight + Innovations; Copyright (C) 2006-2010 by the following authors: + Artur Huillet <arthur.huillet@free.fr> (ahuillet), Ben + Skeggs (darktama, darktama_), B. R. + <koala_br@users.sourceforge.net> (koala_br), Carlos Martin + <carlosmn@users.sf.net> (carlosmn), Christoph Bumiller + <e0425955@student.tuwien.ac.at> (calim, chrisbmr), Dawid + Gajownik <gajownik@users.sf.net> (gajownik), Dmitry + Baryshkov, Dmitry Eremin,Solenikov <lumag@users.sf.net> + (lumag), EdB <edb_@users.sf.net> (edb_), Erik Waling + <erikwailing@users.sf.net> (erikwaling), Francisco Jerez + <currojerez@riseup.net> (curro), imirkin + <imirkin@users.sf.net> (imirkin), jb17bsome + <jb17bsome@bellsouth.net> (jb17bsome), Jeremy Kolb + <kjeremy@users.sf.net> (kjeremy), Laurent Carlier + <lordheavym@gmail.com> (lordheavy), Luca Barbieri + <luca@luca,barbieri.com> (lb, lb1), Maarten Maathuis + <madman2003@gmail.com> (stillunknown), Marcin Kościelnicki + <koriakin@0x04.net> (mwk, koriakin), Mark Carey + <mark.carey@gmail.com> (careym), Matthieu Castet + <matthieu.castet@parrot.com> (mat,c), nvidiaman + <nvidiaman@users.sf.net> (nvidiaman), Patrice Mandin + <patmandin@gmail.com> (pmandin, pmdata), Pekka Paalanen + <pq@iki.fi> (pq, ppaalanen), Peter Popov + <ironpeter@users.sf.net> (ironpeter), Richard Hughes + <hughsient@users.sf.net> (hughsient), Rudi Cilibrasi + <cilibrar@users.sf.net> (cilibrar), Serge Martin, Simon + Raffeiner, Stephane Loeuillet <leroutier@users.sf.net> + (leroutier), Stephane Marchesin + <stephane.marchesin@gmail.com> (marcheu), sturmflut + <sturmflut@users.sf.net> (sturmflut), Sylvain Munaut + <tnt@246tNt.com>, Victor Stinner + <victor.stinner@haypocalc.com> (haypo), Wladmir van der + Laan <laanwj@gmail.com> (miathan6), Younes Manton + <younes.m@gmail.com> (ymanton) + </para> + + </sect2> + + <sect2 id="licMicrosoft"> + + <title>Microsoft Software License</title> + + <para> + MICROSOFT SOFTWARE LICENSE TERMS + </para> + + <para> + MICROSOFT WINDOWS DRIVER KIT + </para> + + <para> + These license terms are an agreement between Microsoft + Corporation (or based on where you live, one of its affiliates) + and you. Please read them. They apply to the software named + above, which includes the media on which you received it, if + any. The terms also apply to any Microsoft + </para> + + <itemizedlist> + + <listitem> + <para> + updates, + </para> + </listitem> + + <listitem> + <para> + supplements, + </para> + </listitem> + + <listitem> + <para> + Internet-based services, and + </para> + </listitem> + + <listitem> + <para> + support services + </para> + </listitem> + + </itemizedlist> + + <para> + for this software, unless other terms accompany those items. If + so, those terms apply. + By using the software, you accept these terms. If you do not + accept them, do not use the software. + </para> + + <para> + If you comply with these license terms, you have the rights below. + </para> + + <orderedlist> + + <listitem> + <para> + INSTALLATION AND USE RIGHTS. + </para> + + <orderedlist> + + <listitem> + <para> + Installation and Use. One user may install and use any + number of copies of the software on your devices to + design, develop and test your programs. + </para> + </listitem> + + <listitem> + <para> + Included Microsoft Programs. The software contains + other Microsoft programs. In some cases, those programs + and the license terms that apply to your use of them are + addressed specifically in these license terms. For all + other included Microsoft programs, these license terms + govern your use. + </para> + </listitem> + + <listitem> + <para> + Device Simulation Framework. One user may install and + use any number of copies of the Device Simulation + Framework on your devices for the sole purpose of + testing the interoperability of your devices, drivers + and firmware with Windows. For the avoidance of doubt, + the Device Simulation Framework shall not be used for + testing software you have designed and developed using a + software development kit other than the Windows Driver + Kit. + </para> + </listitem> + + <listitem> + <para> + Third Party Programs. The software contains third party + programs. These license terms as well as any license + terms accompanying the third party program files apply + to your use of them. + </para> + </listitem> + + </orderedlist> + + </listitem> + + <listitem> + <para> + ADDITIONAL LICENSING REQUIREMENTS AND/OR USE RIGHTS. + </para> + + <orderedlist> + + <listitem> + <para> + Distributable Code. The software contains code that you + are permitted to distribute in programs you develop if + you comply with the terms below. + </para> + + <orderedlist> + + <listitem> + <para> + Right to Use and Distribute. The code and text + files listed below are “Distributable Code.” + </para> + + <itemizedlist> + + <listitem> + <para> + REDIST.TXT Files. You may copy and distribute + the object code form of code listed in + REDIST.TXT files. + </para> + </listitem> + + <listitem> + <para> + Sample Code. You may modify, copy and distribute + only in object code form the sample code found + in the SRC directory of the Windows Driver Kit, + except that you may also modify, copy, and + distribute in source code form the sample code + listed in the SAMPLES.TXT file. + </para> + </listitem> + + <listitem> + <para> + Third Party Distribution. You may permit + distributors of your programs to copy and + distribute the Distributable Code as part of + those programs. + </para> + </listitem> + + </itemizedlist> + + </listitem> + <listitem> + <para> + Distribution Requirements. For any Distributable + Code you distribute, you must + </para> + + <itemizedlist> + + <listitem> + <para> + add significant primary functionality to it in + your programs; + </para> + </listitem> + + <listitem> + <para> + require distributors and external end users to + agree to terms that protect it at least as much + as this agreement; + </para> + </listitem> + + <listitem> + <para> + display your valid copyright notice on your + programs; and + </para> + </listitem> + + <listitem> + <para> + indemnify, defend, and hold harmless Microsoft + from any claims, including attorneys’ fees, + related to the distribution or use of your + programs. + </para> + </listitem> + + </itemizedlist> + + </listitem> + <listitem> + <para> + Distribution Restrictions. You may not + </para> + + <itemizedlist> + + <listitem> + <para> + alter any copyright, trademark or patent notice + in the Distributable Code; + </para> + </listitem> + + <listitem> + <para> + use Microsoft’s trademarks in your programs’ + names or in a way that suggests your programs + come from or are endorsed by Microsoft; + </para> + </listitem> + + <listitem> + <para> + distribute Distributable Code to run on a + platform other than the Windows platform; + </para> + </listitem> + + <listitem> + <para> + include Distributable Code in malicious, + deceptive or unlawful programs; or + </para> + </listitem> + + <listitem> + <para> + modify or distribute the source code of any + Distributable Code so that any part of it + becomes subject to an Excluded License. An + Excluded License is one that requires, as a + condition of use, modification or distribution, + that + </para> + </listitem> + + <listitem> + <para> + the code be disclosed or distributed in source + code form; or + </para> + </listitem> + + <listitem> + <para> + others have the right to modify it. + </para> + </listitem> + + </itemizedlist> + + </listitem> + + </orderedlist> + + </listitem> + + </orderedlist> + + </listitem> + <listitem> + <para> + Scope of License. The software is licensed, not + sold. This agreement only gives you some rights to + use the software. Microsoft reserves all other + rights. Unless applicable law gives you more rights + despite this limitation, you may use the software + only as expressly permitted in this agreement. In + doing so, you must comply with any technical + limitations in the software that only allow you to + use it in certain ways. You may not + </para> + + <itemizedlist> + + <listitem> + <para> + work around any technical limitations in the + software; + </para> + </listitem> + + <listitem> + <para> + reverse engineer, decompile or disassemble the + software, except and only to the extent that + applicable law expressly permits, despite this + limitation; + </para> + </listitem> + + <listitem> + <para> + make more copies of the software than specified + in this agreement or allowed by applicable law, + despite this limitation; + </para> + </listitem> + + <listitem> + <para> + publish the software for others to copy; + </para> + </listitem> + + <listitem> + <para> + rent, lease or lend the software; + </para> + </listitem> + + <listitem> + <para> + transfer the software or this agreement to any + third party; or + </para> + </listitem> + + <listitem> + <para> + use the software for commercial software hosting + services. + </para> + </listitem> + + </itemizedlist> + </listitem> + <listitem> + <para> + BACKUP COPY. You may make one backup copy of the + software. You may use it only to reinstall the + software. + </para> + </listitem> + + <listitem> + <para> + DOCUMENTATION. Any person that has valid access to + your computer or internal network may copy and use + the documentation for your internal, reference + purposes. + </para> + </listitem> + + <listitem> + <para> + Export Restrictions. The software is subject to + United States export laws and regulations. You must + comply with all domestic and international export + laws and regulations that apply to the software. + These laws include restrictions on destinations, end + users and end use. For additional information, see + www.microsoft.com/exporting. + </para> + </listitem> + + <listitem> + <para> + SUPPORT SERVICES. Because this software is “as is,” + we may not provide support services for it. + </para> + </listitem> + + <listitem> + <para> + Entire Agreement. This agreement, and the terms for + supplements, updates, Internet-based services and + support services that you use, are the entire + agreement for the software and support services + </para> + </listitem> + <listitem> + <para> + Applicable Law. + </para> + + <orderedlist> + + <listitem> + <para> + United States. If you acquired the software in + the United States, Washington state law governs + the interpretation of this agreement and applies + to claims for breach of it, regardless of + conflict of laws principles. The laws of the + state where you live govern all other claims, + including claims under state consumer protection + laws, unfair competition laws, and in tort. + </para> + </listitem> + + <listitem> + <para> + Outside the United States. If you acquired the + software in any other country, the laws of that + country apply. + </para> + </listitem> + + </orderedlist> + </listitem> + <listitem> + <para> + Legal Effect. This agreement describes certain + legal rights. You may have other rights under the + laws of your country. You may also have rights with + respect to the party from whom you acquired the + software. This agreement does not change your + rights under the laws of your country if the laws of + your country do not permit it to do so. + </para> + </listitem> + + <listitem> + <para> + Disclaimer of Warranty. The software is licensed + “as-is.” You bear the risk of using it. Microsoft + gives no express warranties, guarantees or + conditions. You may have additional consumer rights + under your local laws which this agreement cannot + change. To the extent permitted under your local + laws, Microsoft excludes the implied warranties of + merchantability, fitness for a particular purpose + and non-infringement. + </para> + </listitem> + + <listitem> + <para> + Limitation on and Exclusion of Remedies and Damages. + You can recover from Microsoft and its suppliers + only direct damages up to U.S. $5.00. You cannot + recover any other damages, including consequential, + lost profits, special, indirect or incidental + damages. + This limitation applies to + </para> + + <itemizedlist> + + <listitem> + <para> + anything related to the software, services, + content (including code) on third party Internet + sites, or third party programs; and + </para> + </listitem> + + <listitem> + <para> + claims for breach of contract, breach of + warranty, guarantee or condition, strict + liability, negligence, or other tort to the + extent permitted by applicable law. + </para> + </listitem> + </itemizedlist> + + <para> + It also applies even if Microsoft knew or should have known + about the possibility of the damages. The above limitation + or exclusion may not apply to you because your country may + not allow the exclusion or limitation of incidental, + consequential or other damages. + </para> + + </listitem> + </orderedlist> + + <para> + Please note: As this software is distributed in Quebec, + Canada, some of the clauses in this agreement are provided + below in French. + </para> + + <para> + Remarque : Ce logiciel étant distribué au Québec, Canada, + certaines des clauses dans ce contrat sont fournies + ci-dessous en français. + </para> + + <para> + EXONÉRATION DE GARANTIE. Le logiciel visé par une licence + est offert « tel quel ». Toute utilisation de ce logiciel + est à votre seule risque et péril. Microsoft n’accorde + aucune autre garantie expresse. Vous pouvez bénéficier de + droits additionnels en vertu du droit local sur la + protection des consommateurs, que ce contrat ne peut + modifier. La ou elles sont permises par le droit locale, les + garanties implicites de qualité marchande, d’adéquation à un + usage particulier et d’absence de contrefaçon sont exclues. + </para> + + <para> + LIMITATION DES DOMMAGES-INTÉRÊTS ET EXCLUSION DE + RESPONSABILITÉ POUR LES DOMMAGES. Vous pouvez obtenir de + Microsoft et de ses fournisseurs une indemnisation en cas de + dommages directs uniquement à hauteur de 5,00 $ US. Vous ne + pouvez prétendre à aucune indemnisation pour les autres + dommages, y compris les dommages spéciaux, indirects ou + accessoires et pertes de bénéfices. + </para> + + <para> + Cette limitation concerne : + </para> + + <itemizedlist> + + <listitem> + <para> + tout ce qui est relié au logiciel, aux services ou au + contenu (y compris le code) figurant sur des sites Internet + tiers ou dans des programmes tiers ; et + </para> + </listitem> + + <listitem> + <para> + les réclamations au titre de violation de contrat ou de + garantie, ou au titre de responsabilité stricte, de + négligence ou d’une autre faute dans la limite autorisée par + la loi en vigueur. + </para> + </listitem> + + </itemizedlist> + + <para> + Elle s’applique également, même si Microsoft connaissait ou + devrait connaître l’éventualité d’un tel dommage. Si votre pays + n’autorise pas l’exclusion ou la limitation de responsabilité + pour les dommages indirects, accessoires ou de quelque nature + que ce soit, il se peut que la limitation ou l’exclusion + ci-dessus ne s’appliquera pas à votre égard. + </para> + + <para> + EFFET JURIDIQUE. Le présent contrat décrit certains droits + juridiques. Vous pourriez avoir d’autres droits prévus par les + lois de votre pays. Le présent contrat ne modifie pas les + droits que vous confèrent les lois de votre pays si celles-ci ne + le permettent pas. + </para> + + </sect2> + + <sect2 id="licCPython"> + + <title>Python License</title> + + <para> + A. HISTORY OF THE SOFTWARE + ========================== + </para> + + <para> + Python was created in the early 1990s by Guido van Rossum at + Stichting Mathematisch Centrum (CWI, see http://www.cwi.nl) in + the Netherlands as a successor of a language called ABC. Guido + remains Python's principal author, although it includes many + contributions from others. + </para> + + <para> + In 1995, Guido continued his work on Python at the Corporation + for National Research Initiatives (CNRI, see + http://www.cnri.reston.va.us) in Reston, Virginia where + he released several versions of the software. + </para> + + <para> + In May 2000, Guido and the Python core development team moved to + BeOpen.com to form the BeOpen PythonLabs team. In October of + the same year, the PythonLabs team moved to Digital Creations, + which became Zope Corporation. In 2001, the Python Software + Foundation (PSF, see https://www.python.org/psf/) was formed, a + non-profit organization created specifically to own + Python-related Intellectual Property. Zope Corporation was a + sponsoring member of the PSF. + </para> + + <para> + All Python releases are Open Source (see + http://www.opensource.org for the Open Source Definition). + Historically, most, but not all, Python releases have also been + GPL-compatible; the table below summarizes the various releases. + </para> + + <table id="Python-releases" tabstyle="oracle-all"> + <title>Python releases</title> + <tgroup cols="5" align="center"> + <thead> + <row> + <entry><para> + <emphasis role="bold">Release</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Derived from</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Year</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Owner</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">GPL-compatible? (1)</emphasis> + </para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para> + 0.9.0 thru 1.2 + </para></entry> + <entry><para> + + </para></entry> + <entry><para> + 1991-1995 + </para></entry> + <entry><para> + CWI + </para></entry> + <entry><para> + yes + </para></entry> + </row> + <row> + <entry><para> + 0.9.0 thru 1.2 + </para></entry> + <entry><para> + + </para></entry> + <entry><para> + 1991-1995 + </para></entry> + <entry><para> + CWI + </para></entry> + <entry><para> + yes + </para></entry> + </row> + <row> + <entry><para> + 1.3 thru 1.5.2 + </para></entry> + <entry><para> + 1.2 + </para></entry> + <entry><para> + 1995-1999 + </para></entry> + <entry><para> + CNRI + </para></entry> + <entry><para> + yes + </para></entry> + </row> + <row> + <entry><para> + 1.6 + </para></entry> + <entry><para> + 1.5.2 + </para></entry> + <entry><para> + 2000 + </para></entry> + <entry><para> + CNRI + </para></entry> + <entry><para> + no + </para></entry> + </row> + <row> + <entry><para> + 2.0 + </para></entry> + <entry><para> + 1.6 + </para></entry> + <entry><para> + 2000 + </para></entry> + <entry><para> + BeOpen.com + </para></entry> + <entry><para> + no + </para></entry> + </row> + <row> + <entry><para> + 1.6.1 + </para></entry> + <entry><para> + 1.6 + </para></entry> + <entry><para> + 2001 + </para></entry> + <entry><para> + CNRI + </para></entry> + <entry><para> + yes (2) + </para></entry> + </row> + <row> + <entry><para> + 2.1 + </para></entry> + <entry><para> + 2.0+1.6.1 + </para></entry> + <entry><para> + 2001 + </para></entry> + <entry><para> + PSF + </para></entry> + <entry><para> + yes + </para></entry> + </row> + <row> + <entry><para> + 2.0.1 + </para></entry> + <entry><para> + 2.0+1.6.1 + </para></entry> + <entry><para> + 2001 + </para></entry> + <entry><para> + PSF + </para></entry> + <entry><para> + yes + </para></entry> + </row> + <row> + <entry><para> + 2.1.1 + </para></entry> + <entry><para> + 2.1+2.0.1 + </para></entry> + <entry><para> + 2001 + </para></entry> + <entry><para> + PSF + </para></entry> + <entry><para> + yes + </para></entry> + </row> + <row> + <entry><para> + 2.1.2 + </para></entry> + <entry><para> + 2.1.1 + </para></entry> + <entry><para> + 2002 + </para></entry> + <entry><para> + PSF + </para></entry> + <entry><para> + yes + </para></entry> + </row> + <row> + <entry><para> + 2.1.3 + </para></entry> + <entry><para> + 2.1.2 + </para></entry> + <entry><para> + 2002 + </para></entry> + <entry><para> + PSF + </para></entry> + <entry><para> + yes + </para></entry> + </row> + <row> + <entry><para> + 2.2 and above + </para></entry> + <entry><para> + 2.1.1 + </para></entry> + <entry><para> + 2001-now + </para></entry> + <entry><para> + PSF + </para></entry> + <entry><para> + yes + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + Footnotes: + </para> + + <para> + (1) GPL-compatible doesn't mean that we're distributing Python + under the GPL. All Python licenses, unlike the GPL, let you + distribute a modified version without making your changes open + source. The GPL-compatible licenses make it possible to combine + Python with other software that is released under the GPL; the + others don't. + </para> + + <para> + (2) According to Richard Stallman, 1.6.1 is not GPL-compatible, + because its license has a choice of law clause. According to + CNRI, however, Stallman's lawyer has told CNRI's lawyer that + 1.6.1 is "not incompatible" with the GPL. + </para> + + <para> + Thanks to the many outside volunteers who have worked under + Guido's direction to make these releases possible. + </para> + + <para> + B. TERMS AND CONDITIONS FOR ACCESSING OR OTHERWISE USING PYTHON + =============================================================== + </para> + + <para> + Python software and documentation are licensed under the + Python Software Foundation License Version 2. + </para> + + <para> + Starting with Python 3.8.6, examples, recipes, and other code in + the documentation are dual licensed under the PSF License + Version 2 and the Zero-Clause BSD license. + </para> + + <para> + Some software incorporated into Python is under different + licenses. The licenses are listed with code falling under that + license. + </para> + + <para> + PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2 + -------------------------------------------- + </para> + + <para> + 1. This LICENSE AGREEMENT is between the Python Software + Foundation ("PSF"), and the Individual or Organization + ("Licensee") accessing and otherwise using this software + ("Python") in source or binary form and its associated + documentation. + </para> + + <para> + 2. Subject to the terms and conditions of this License + Agreement, PSF hereby grants Licensee a nonexclusive, + royalty-free, world-wide license to reproduce, analyze, test, + perform and/or display publicly, prepare derivative works, + distribute, and otherwise use Python alone or in any derivative + version, provided, however, that PSF's License Agreement and + PSF's notice of copyright, i.e., "Copyright (c) 2001, 2002, + 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, + 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022 + Python Software Foundation; All Rights Reserved" are retained in + Python alone or in any derivative version prepared by Licensee. + </para> + + <para> + 3. In the event Licensee prepares a derivative work that is based on + or incorporates Python or any part thereof, and wants to make + the derivative work available to others as provided herein, then + Licensee hereby agrees to include in any such work a brief summary of + the changes made to Python. + </para> + + <para> + 4. PSF is making Python available to Licensee on an "AS IS" + basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR + IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO + AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY + OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON + WILL NOT INFRINGE ANY THIRD PARTY RIGHTS. + </para> + + <para> + 5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF + PYTHON FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR + LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING + PYTHON, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE + POSSIBILITY THEREOF. + </para> + + <para> + 6. This License Agreement will automatically terminate upon a + material breach of its terms and conditions. + </para> + + <para> + 7. Nothing in this License Agreement shall be deemed to create + any relationship of agency, partnership, or joint venture + between PSF and Licensee. This License Agreement does not grant + permission to use PSF trademarks or trade name in a trademark + sense to endorse or promote products or services of Licensee, or + any third party. + </para> + + <para> + 8. By copying, installing or otherwise using Python, Licensee + agrees to be bound by the terms and conditions of this License + Agreement. + </para> + + <para> + BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0 + ------------------------------------------- + </para> + + <para> + BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1 + </para> + + <para> + 1. This LICENSE AGREEMENT is between BeOpen.com ("BeOpen"), having an + office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the + Individual or Organization ("Licensee") accessing and otherwise using + this software in source or binary form and its associated + documentation ("the Software"). + </para> + + <para> + 2. Subject to the terms and conditions of this BeOpen Python + License Agreement, BeOpen hereby grants Licensee a + non-exclusive, royalty-free, world-wide license to reproduce, + analyze, test, perform and/or display publicly, prepare + derivative works, distribute, and otherwise use the Software + alone or in any derivative version, provided, however, that the + BeOpen Python License is retained in the Software, alone or in + any derivative version prepared by Licensee. + </para> + + <para> + 3. BeOpen is making the Software available to Licensee on an "AS + IS" basis. BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, + EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, + BEOPEN MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF + MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT + THE USE OF THE SOFTWARE WILL NOT INFRINGE ANY THIRD PARTY + RIGHTS. + </para> + + <para> + 4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF + THE SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL + DAMAGES OR LOSS AS A RESULT OF USING, MODIFYING OR DISTRIBUTING + THE SOFTWARE, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE + POSSIBILITY THEREOF. + </para> + + <para> + 5. This License Agreement will automatically terminate upon a + material breach of its terms and conditions. + </para> + + <para> + 6. This License Agreement shall be governed by and interpreted + in all respects by the law of the State of California, excluding + conflict of law provisions. Nothing in this License Agreement + shall be deemed to create any relationship of agency, + partnership, or joint venture between BeOpen and Licensee. This + License Agreement does not grant permission to use BeOpen + trademarks or trade names in a trademark sense to endorse or + promote products or services of Licensee, or any third party. + As an exception, the "BeOpen Python" logos available at + http://www.pythonlabs.com/logos.html may be used according to + the permissions granted on that web page. + </para> + + <para> + 7. By copying, installing or otherwise using the software, + Licensee agrees to be bound by the terms and conditions of this + License Agreement. + </para> + + <para> + CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1 + --------------------------------------- + </para> + + <para> + 1. This LICENSE AGREEMENT is between the Corporation for + National Research Initiatives, having an office at 1895 Preston + White Drive, Reston, VA 20191 ("CNRI"), and the Individual or + Organization ("Licensee") accessing and otherwise using Python + 1.6.1 software in source or binary form and its associated + documentation. + </para> + + <para> + 2. Subject to the terms and conditions of this License + Agreement, CNRI hereby grants Licensee a nonexclusive, + royalty-free, world-wide license to reproduce, analyze, test, + perform and/or display publicly, prepare derivative works, + distribute, and otherwise use Python 1.6.1 alone or in any + derivative version, provided, however, that CNRI's License + Agreement and CNRI's notice of copyright, i.e., "Copyright (c) + 1995-2001 Corporation for National Research Initiatives; All + Rights Reserved" are retained in Python 1.6.1 alone or in any + derivative version prepared by Licensee. Alternately, in lieu + of CNRI's License Agreement, Licensee may substitute the + following text (omitting the quotes): "Python 1.6.1 is made + available subject to the terms and conditions in CNRI's License + Agreement. This Agreement together with Python 1.6.1 may be + located on the Internet using the following unique, persistent + identifier (known as a handle): 1895.22/1013. This Agreement + may also be obtained from a proxy server on the Internet using + the following URL: http://hdl.handle.net/1895.22/1013". + </para> + + <para> + 3. In the event Licensee prepares a derivative work that is + based on or incorporates Python 1.6.1 or any part thereof, and + wants to make the derivative work available to others as + provided herein, then Licensee hereby agrees to include in any + such work a brief summary of the changes made to Python 1.6.1. + </para> + + <para> + 4. CNRI is making Python 1.6.1 available to Licensee on an "AS + IS" basis. CNRI MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS + OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, CNRI MAKES + NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF + MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT + THE USE OF PYTHON 1.6.1 WILL NOT INFRINGE ANY THIRD PARTY + RIGHTS. + </para> + + <para> + 5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF + PYTHON 1.6.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL + DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR + OTHERWISE USING PYTHON 1.6.1, OR ANY DERIVATIVE THEREOF, EVEN IF + ADVISED OF THE POSSIBILITY THEREOF. + </para> + + <para> + 6. This License Agreement will automatically terminate upon a + material breach of its terms and conditions. + </para> + + <para> + 7. This License Agreement shall be governed by the federal + intellectual property law of the United States, including + without limitation the federal copyright law, and, to the extent + such U.S. federal law does not apply, by the law of the + Commonwealth of Virginia, excluding Virginia's conflict of law + provisions. Notwithstanding the foregoing, with regard to + derivative works based on Python 1.6.1 that incorporate + non-separable material that was previously distributed under the + GNU General Public License (GPL), the law of the Commonwealth of + Virginia shall govern this License Agreement only as to issues + arising under or with respect to Paragraphs 4, 5, and 7 of this + License Agreement. Nothing in this License Agreement shall be + deemed to create any relationship of agency, partnership, or + joint venture between CNRI and Licensee. This License Agreement + does not grant permission to use CNRI trademarks or trade name + in a trademark sense to endorse or promote products or services + of Licensee, or any third party. + </para> + + <para> + 8. By clicking on the "ACCEPT" button where indicated, or by + copying, installing or otherwise using Python 1.6.1, Licensee + agrees to be bound by the terms and conditions of this License + Agreement. + </para> + + <para> + ACCEPT + </para> + + <para> + CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2 + -------------------------------------------------- + </para> + + <para> + Copyright (c) 1991 - 1995, Stichting Mathematisch Centrum + Amsterdam, The Netherlands. All rights reserved. + </para> + + <para> + Permission to use, copy, modify, and distribute this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appear in all + copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the name of + Stichting Mathematisch Centrum or CWI not be used in advertising + or publicity pertaining to distribution of the software without + specific, written prior permission. + </para> + + <para> + STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH + REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING + MATHEMATISCH CENTRUM BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + <para> + ZERO-CLAUSE BSD LICENSE FOR CODE IN THE PYTHON DOCUMENTATION + ---------------------------------------------------------------------- + </para> + + <para> + Permission to use, copy, modify, and/or distribute this software + for any purpose with or without fee is hereby granted. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH + REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, + INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR + OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licBSD-SoftFloat"> + + <title>License for Berkeley SoftFloat Release 3e</title> + + <para> + John R. Hauser + 2018 January 20 + </para> + + <para> + The following applies to the whole of SoftFloat Release 3e as + well as to each source file individually. + </para> + + <para> + Copyright 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 The + Regents of the University of California. All rights reserved. + </para> + + <para> + Redistribution and use in source and binary forms, with or + without modification, are permitted provided that the following + conditions are met: + </para> + + <orderedlist> + + <listitem> + <para> + Redistributions of source code must retain the above + copyright notice, this list of conditions, and the following + disclaimer. + </para> + </listitem> + + <listitem> + <para> + Redistributions in binary form must reproduce the above + copyright notice, this list of conditions, and the following + disclaimer in the documentation and/or other materials + provided with the distribution. + </para> + </listitem> + + <listitem> + <para> + Neither the name of the University nor the names of its + contributors may be used to endorse or promote products + derived from this software without specific prior written + permission. + </para> + </listitem> + + </orderedlist> + + <para> + THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS + IS", AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS FOR A PARTICULAR PURPOSE, ARE DISCLAIMED. IN NO EVENT + SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF + THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + SUCH DAMAGE. + </para> + + </sect2> + + <sect2 id="licBSD-3Clause-Glslang"> + + <title>BSD 3-Clause License for Glslang</title> + + <para> + Copyright (C) 2015-2018 Google, Inc.; Copyright (C) <various + other dates and companies> + </para> + + <para> + All rights reserved. + </para> + + <para> + Redistribution and use in source and binary forms, with or + without modification, are permitted provided that the following + conditions are met: + </para> + + <orderedlist> + + <listitem> + <para> + Redistributions of source code must retain the above + copyright notice, this list of conditions, and the following + disclaimer. + </para> + </listitem> + + <listitem> + <para> + Redistributions in binary form must reproduce the above + copyright notice, this list of conditions, and the following + disclaimer in the documentation and/or other materials + provided with the distribution. + </para> + </listitem> + + <listitem> + <para> + Neither the name of 3Dlabs Inc. Ltd. nor the names of its + contributors may be used to endorse or promote products + derived from this software without specific prior written + permission. + </para> + </listitem> + + </orderedlist> + + <para> + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND + CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR + CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED + AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING + IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF + THE POSSIBILITY OF SUCH DAMAGE. + </para> + + </sect2> + + <sect2 id="licBSD-2Clause-Glslang"> + + <title>BSD 2-Clause License for Glslang</title> + + <para> + + </para> + + <para> + Redistribution and use in source and binary forms, with or + without modification, are permitted provided that the following + conditions are met: + </para> + + <orderedlist> + + <listitem> + <para> + Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. + </para> + </listitem> + + <listitem> + <para> + Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials + provided with the distribution. + </para> + </listitem> + + </orderedlist> + + <para> + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND + CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR + CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED + AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING + IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF + THE POSSIBILITY OF SUCH DAMAGE. + </para> + + </sect2> + + <sect2 id="licGPL-Bison-Glslang"> + + <title>GNU General Public License (GPL) License with Bison Exception for Glslang</title> + + <para> + GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007 + </para> + + <para> + Copyright (C) 2007 Free Software Foundation, Inc. + <http://fsf.org/> Everyone is permitted to copy and distribute + verbatim copies of this license document, but changing it is not + allowed. + </para> + + <para> + Preamble + </para> + + <para> + The GNU General Public License is a free, copyleft license for + software and other kinds of works. + </para> + + <para> + The licenses for most software and other practical works are + designed to take away your freedom to share and change the + works. By contrast, the GNU General Public License is intended + to guarantee your freedom to share and change all versions of a + program--to make sure it remains free software for all its + users. We, the Free Software Foundation, use the GNU General + Public License for most of our software; it applies also to any + other work released this way by its authors. You can apply it + to your programs, too. + </para> + + <para> + When we speak of free software, we are referring to freedom, not + price. Our General Public Licenses are designed to make sure + that you have the freedom to distribute copies of free software + (and charge for them if you wish), that you receive source code + or can get it if you want it, that you can change the software + or use pieces of it in new free programs, and that you know you + can do these things. + </para> + + <para> + To protect your rights, we need to prevent others from denying + you these rights or asking you to surrender the rights. + Therefore, you have certain responsibilities if you distribute + copies of the software, or if you modify it: responsibilities to + respect the freedom of others. + </para> + + <para> + For example, if you distribute copies of such a program, whether + gratis or for a fee, you must pass on to the recipients the same + freedoms that you received. You must make sure that they, too, + receive or can get the source code. And you must show them + these terms so they know their rights. + </para> + + <para> + Developers that use the GNU GPL protect your rights with two + steps: (1) assert copyright on the software, and (2) offer you + this License giving you legal permission to copy, distribute + and/or modify it. + </para> + + <para> + For the developers' and authors' protection, the GPL clearly + explains that there is no warranty for this free software. For + both users' and authors' sake, the GPL requires that modified + versions be marked as changed, so that their problems will not + be attributed erroneously to authors of previous versions. + </para> + + <para> + Some devices are designed to deny users access to install or run + modified versions of the software inside them, although the + manufacturer can do so. This is fundamentally incompatible with + the aim of protecting users' freedom to change the software. + The systematic pattern of such abuse occurs in the area of + products for individuals to use, which is precisely where it is + most unacceptable. Therefore, we have designed this version of + the GPL to prohibit the practice for those products. If such + problems arise substantially in other domains, we stand ready to + extend this provision to those domains in future versions of the + GPL, as needed to protect the freedom of users. + </para> + + <para> + Finally, every program is threatened constantly by software + patents. States should not allow patents to restrict + development and use of software on general-purpose computers, + but in those that do, we wish to avoid the special danger that + patents applied to a free program could make it effectively + proprietary. To prevent this, the GPL assures that patents + cannot be used to render the program non-free. + </para> + + <para> + The precise terms and conditions for copying, distribution and + modification follow. + </para> + + <para> + TERMS AND CONDITIONS + </para> + + <para> + 0. Definitions. + </para> + + <para> + "This License" refers to version 3 of the GNU General Public + License. + </para> + + <para> + "Copyright" also means copyright-like laws that apply to other + kinds of works, such as semiconductor masks. + </para> + + <para> + "The Program" refers to any copyrightable work licensed under + this License. Each licensee is addressed as "you". "Licensees" + and "recipients" may be individuals or organizations. + </para> + + <para> + To "modify" a work means to copy from or adapt all or part of + the work in a fashion requiring copyright permission, other than + the making of an exact copy. The resulting work is called a + "modified version" of the earlier work or a work "based on" the + earlier work. + </para> + + <para> + A "covered work" means either the unmodified Program or a work + based on the Program. + </para> + + <para> + To "propagate" a work means to do anything with it that, without + permission, would make you directly or secondarily liable for + infringement under applicable copyright law, except executing it + on a computer or modifying a private copy. Propagation includes + copying, distribution (with or without modification), making + available to the public, and in some countries other activities + as well. + </para> + + <para> + To "convey" a work means any kind of propagation that enables + other parties to make or receive copies. Mere interaction with + a user through a computer network, with no transfer of a copy, + is not conveying. + </para> + + <para> + An interactive user interface displays "Appropriate Legal + Notices" to the extent that it includes a convenient and + prominently visible feature that (1) displays an appropriate + copyright notice, and (2) tells the user that there is no + warranty for the work (except to the extent that warranties are + provided), that licensees may convey the work under this + License, and how to view a copy of this License. If the + interface presents a list of user commands or options, such as a + menu, a prominent item in the list meets this criterion. + </para> + + <para> + 1. Source Code. + </para> + + <para> + The "source code" for a work means the preferred form of the + work for making modifications to it. "Object code" means any + non-source form of a work. + </para> + + <para> + A "Standard Interface" means an interface that either is an + official standard defined by a recognized standards body, or, in + the case of interfaces specified for a particular programming + language, one that is widely used among developers working in + that language. + </para> + + <para> + The "System Libraries" of an executable work include anything, + other than the work as a whole, that (a) is included in the + normal form of packaging a Major Component, but which is not + part of that Major Component, and (b) serves only to enable use + of the work with that Major Component, or to implement a + Standard Interface for which an implementation is available to + the public in source code form. A "Major Component", in this + context, means a major essential component (kernel, window + system, and so on) of the specific operating system (if any) on + which the executable work runs, or a compiler used to produce + the work, or an object code interpreter used to run it. + </para> + + <para> + The "Corresponding Source" for a work in object code form means + all the source code needed to generate, install, and (for an + executable work) run the object code and to modify the work, + including scripts to control those activities. However, it does + not include the work's System Libraries, or general-purpose + tools or generally available free programs which are used + unmodified in performing those activities but which are not part + of the work. For example, Corresponding Source includes + interface definition files associated with source files for the + work, and the source code for shared libraries and dynamically + linked subprograms that the work is specifically designed to + require, such as by intimate data communication or control flow + between those subprograms and other parts of the work. + </para> + + <para> + The Corresponding Source need not include anything that users + can regenerate automatically from other parts of the + Corresponding Source. + </para> + + <para> + The Corresponding Source for a work in source code form is that + same work. + </para> + + <para> + 2. Basic Permissions. + </para> + + <para> + All rights granted under this License are granted for the term + of copyright on the Program, and are irrevocable provided the + stated conditions are met. This License explicitly affirms your + unlimited permission to run the unmodified Program. The output + from running a covered work is covered by this License only if + the output, given its content, constitutes a covered work. This + License acknowledges your rights of fair use or other + equivalent, as provided by copyright law. + </para> + + <para> + You may make, run and propagate covered works that you do not + convey, without conditions so long as your license otherwise + remains in force. You may convey covered works to others for + the sole purpose of having them make modifications exclusively + for you, or provide you with facilities for running those works, + provided that you comply with the terms of this License in + conveying all material for which you do not control copyright. + Those thus making or running the covered works for you must do + so exclusively on your behalf, under your direction and control, + on terms that prohibit them from making any copies of your + copyrighted material outside their relationship with you. + </para> + + <para> + Conveying under any other circumstances is permitted solely + under the conditions stated below. Sublicensing is not allowed; + section 10 makes it unnecessary. + </para> + + <para> + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + </para> + + <para> + No covered work shall be deemed part of an effective + technological measure under any applicable law fulfilling + obligations under article 11 of the WIPO copyright treaty + adopted on 20 December 1996, or similar laws prohibiting or + restricting circumvention of such measures. + </para> + + <para> + When you convey a covered work, you waive any legal power to + forbid circumvention of technological measures to the extent + such circumvention is effected by exercising rights under this + License with respect to the covered work, and you disclaim any + intention to limit operation or modification of the work as a + means of enforcing, against the work's users, your or third + parties' legal rights to forbid circumvention of technological + measures. + </para> + + <para> + 4. Conveying Verbatim Copies. + </para> + + <para> + You may convey verbatim copies of the Program's source code as + you receive it, in any medium, provided that you conspicuously + and appropriately publish on each copy an appropriate copyright + notice; keep intact all notices stating that this License and + any non-permissive terms added in accord with section 7 apply to + the code; keep intact all notices of the absence of any + warranty; and give all recipients a copy of this License along + with the Program. + </para> + + <para> + You may charge any price or no price for each copy that you + convey, and you may offer support or warranty protection for a + fee. + </para> + + <para> + 5. Conveying Modified Source Versions. + </para> + + <para> + You may convey a work based on the Program, or the modifications + to produce it from the Program, in the form of source code under + the terms of section 4, provided that you also meet all of these + conditions: + </para> + + <para> + a) The work must carry prominent notices stating that you + modified it, and giving a relevant date. + </para> + + <para> + b) The work must carry prominent notices stating that it is + released under this License and any conditions added under + section 7. This requirement modifies the requirement in section + 4 to "keep intact all notices". + </para> + + <para> + c) You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable section + 7 additional terms, to the whole of the work, and all its parts, + regardless of how they are packaged. This License gives no + permission to license the work in any other way, but it does not + invalidate such permission if you have separately received it. + </para> + + <para> + d) If the work has interactive user interfaces, each must + display Appropriate Legal Notices; however, if the Program has + interactive interfaces that do not display Appropriate Legal + Notices, your work need not make them do so. + </para> + + <para> + A compilation of a covered work with other separate and + independent works, which are not by their nature extensions of + the covered work, and which are not combined with it such as to + form a larger program, in or on a volume of a storage or + distribution medium, is called an "aggregate" if the compilation + and its resulting copyright are not used to limit the access or + legal rights of the compilation's users beyond what the + individual works permit. Inclusion of a covered work in an + aggregate does not cause this License to apply to the other + parts of the aggregate. + </para> + + <para> + 6. Conveying Non-Source Forms. + </para> + + <para> + You may convey a covered work in object code form under the + terms of sections 4 and 5, provided that you also convey the + machine-readable Corresponding Source under the terms of this + License, in one of these ways: + </para> + + <para> + a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + </para> + + <para> + b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that + product model, to give anyone who possesses the object code + either (1) a copy of the Corresponding Source for all the + software in the product that is covered by this License, on a + durable physical medium customarily used for software + interchange, for a price no more than your reasonable cost of + physically performing this conveying of source, or (2) access to + copy the Corresponding Source from a network server at no + charge. + </para> + + <para> + c) Convey individual copies of the object code with a copy of + the written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, + and only if you received the object code with such an offer, in + accord with subsection 6b. + </para> + + <para> + d) Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to + the Corresponding Source in the same way through the same place + at no further charge. You need not require recipients to copy + the Corresponding Source along with the object code. If the + place to copy the object code is a network server, the + Corresponding Source may be on a different server (operated by + you or a third party) that supports equivalent copying + facilities, provided you maintain clear directions next to the + object code saying where to find the Corresponding Source. + Regardless of what server hosts the Corresponding Source, you + remain obligated to ensure that it is available for as long as + needed to satisfy these requirements. + </para> + + <para> + e) Convey the object code using peer-to-peer transmission, + provided you inform other peers where the object code and + Corresponding Source of the work are being offered to the + general public at no charge under subsection 6d. + </para> + + <para> + A separable portion of the object code, whose source code is + excluded from the Corresponding Source as a System Library, need + not be included in conveying the object code work. + </para> + + <para> + A "User Product" is either (1) a "consumer product", which means + any tangible personal property which is normally used for + personal, family, or household purposes, or (2) anything + designed or sold for incorporation into a dwelling. In + determining whether a product is a consumer product, doubtful + cases shall be resolved in favor of coverage. For a particular + product received by a particular user, "normally used" refers to + a typical or common use of that class of product, regardless of + the status of the particular user or of the way in which the + particular user actually uses, or expects or is expected to use, + the product. A product is a consumer product regardless of + whether the product has substantial commercial, industrial or + non-consumer uses, unless such uses represent the only + significant mode of use of the product. + </para> + + <para> + "Installation Information" for a User Product means any methods, + procedures, authorization keys, or other information required to + install and execute modified versions of a covered work in that + User Product from a modified version of its Corresponding + Source. The information must suffice to ensure that the + continued functioning of the modified object code is in no case + prevented or interfered with solely because modification has + been made. + </para> + + <para> + If you convey an object code work under this section in, or + with, or specifically for use in, a User Product, and the + conveying occurs as part of a transaction in which the right of + possession and use of the User Product is transferred to the + recipient in perpetuity or for a fixed term (regardless of how + the transaction is characterized), the Corresponding Source + conveyed under this section must be accompanied by the + Installation Information. But this requirement does not apply + if neither you nor any third party retains the ability to + install modified object code on the User Product (for example, + the work has been installed in ROM). + </para> + + <para> + The requirement to provide Installation Information does not + include a requirement to continue to provide support service, + warranty, or updates for a work that has been modified or + installed by the recipient, or for the User Product in which it + has been modified or installed. Access to a network may be + denied when the modification itself materially and adversely + affects the operation of the network or violates the rules and + protocols for communication across the network. + </para> + + <para> + Corresponding Source conveyed, and Installation Information + provided, in accord with this section must be in a format that + is publicly documented (and with an implementation available to + the public in source code form), and must require no special + password or key for unpacking, reading or copying. + </para> + + <para> + 7. Additional Terms. + </para> + + <para> + "Additional permissions" are terms that supplement the terms of + this License by making exceptions from one or more of its + conditions. Additional permissions that are applicable to the + entire Program shall be treated as though they were included in + this License, to the extent that they are valid under applicable + law. If additional permissions apply only to part of the + Program, that part may be used separately under those + permissions, but the entire Program remains governed by this + License without regard to the additional permissions. + </para> + + <para> + When you convey a copy of a covered work, you may at your option + remove any additional permissions from that copy, or from any + part of it. (Additional permissions may be written to require + their own removal in certain cases when you modify the work.) + You may place additional permissions on material, added by you + to a covered work, for which you have or can give appropriate + copyright permission. + </para> + + <para> + Notwithstanding any other provision of this License, for + material you add to a covered work, you may (if authorized by + the copyright holders of that material) supplement the terms of + this License with terms: + </para> + + <para> + a) Disclaiming warranty or limiting liability differently from + the terms of sections 15 and 16 of this License; or + </para> + + <para> + b) Requiring preservation of specified reasonable legal notices + or author attributions in that material or in the Appropriate + Legal Notices displayed by works containing it; or + </para> + + <para> + c) Prohibiting misrepresentation of the origin of that material, + or requiring that modified versions of such material be marked + in reasonable ways as different from the original version; or + </para> + + <para> + d) Limiting the use for publicity purposes of names of licensors + or authors of the material; or + </para> + + <para> + e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + </para> + + <para> + f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified + versions of it) with contractual assumptions of liability to the + recipient, for any liability that these contractual assumptions + directly impose on those licensors and authors. + </para> + + <para> + All other non-permissive additional terms are considered + "further restrictions" within the meaning of section 10. If the + Program as you received it, or any part of it, contains a notice + stating that it is governed by this License along with a term + that is a further restriction, you may remove that term. If a + license document contains a further restriction but permits + relicensing or conveying under this License, you may add to a + covered work material governed by the terms of that license + document, provided that the further restriction does not survive + such relicensing or conveying. + </para> + + <para> + If you add terms to a covered work in accord with this section, + you must place, in the relevant source files, a statement of the + additional terms that apply to those files, or a notice + indicating where to find the applicable terms. + </para> + + <para> + Additional terms, permissive or non-permissive, may be stated in + the form of a separately written license, or stated as + exceptions; the above requirements apply either way. + </para> + + <para> + 8. Termination. + </para> + + <para> + You may not propagate or modify a covered work except as + expressly provided under this License. Any attempt otherwise to + propagate or modify it is void, and will automatically terminate + your rights under this License (including any patent licenses + granted under the third paragraph of section 11). + </para> + + <para> + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly + and finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + </para> + + <para> + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of + the violation by some reasonable means, this is the first time + you have received notice of violation of this License (for any + work) from that copyright holder, and you cure the violation + prior to 30 days after your receipt of the notice. + </para> + + <para> + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from + you under this License. If your rights have been terminated and + not permanently reinstated, you do not qualify to receive new + licenses for the same material under section 10. + </para> + + <para> + 9. Acceptance Not Required for Having Copies. + </para> + + <para> + You are not required to accept this License in order to receive + or run a copy of the Program. Ancillary propagation of a + covered work occurring solely as a consequence of using + peer-to-peer transmission to receive a copy likewise does not + require acceptance. However, nothing other than this License + grants you permission to propagate or modify any covered work. + These actions infringe copyright if you do not accept this + License. Therefore, by modifying or propagating a covered work, + you indicate your acceptance of this License to do so. + </para> + + <para> + 10. Automatic Licensing of Downstream Recipients. + </para> + + <para> + Each time you convey a covered work, the recipient automatically + receives a license from the original licensors, to run, modify + and propagate that work, subject to this License. You are not + responsible for enforcing compliance by third parties with this + License. + </para> + + <para> + An "entity transaction" is a transaction transferring control of + an organization, or substantially all assets of one, or + subdividing an organization, or merging organizations. If + propagation of a covered work results from an entity + transaction, each party to that transaction who receives a copy + of the work also receives whatever licenses to the work the + party's predecessor in interest had or could give under the + previous paragraph, plus a right to possession of the + Corresponding Source of the work from the predecessor in + interest, if the predecessor has it or can get it with + reasonable efforts. + </para> + + <para> + You may not impose any further restrictions on the exercise of + the rights granted or affirmed under this License. For example, + you may not impose a license fee, royalty, or other charge for + exercise of rights granted under this License, and you may not + initiate litigation (including a cross-claim or counterclaim in + a lawsuit) alleging that any patent claim is infringed by + making, using, selling, offering for sale, or importing the + Program or any portion of it. + </para> + + <para> + 11. Patents. + </para> + + <para> + A "contributor" is a copyright holder who authorizes use under + this License of the Program or a work on which the Program is + based. The work thus licensed is called the contributor's + "contributor version". + </para> + + <para> + A contributor's "essential patent claims" are all patent claims + owned or controlled by the contributor, whether already acquired + or hereafter acquired, that would be infringed by some manner, + permitted by this License, of making, using, or selling its + contributor version, but do not include claims that would be + infringed only as a consequence of further modification of the + contributor version. For purposes of this definition, "control" + includes the right to grant patent sublicenses in a manner + consistent with the requirements of this License. + </para> + + <para> + Each contributor grants you a non-exclusive, worldwide, + royalty-free patent license under the contributor's essential + patent claims, to make, use, sell, offer for sale, import and + otherwise run, modify and propagate the contents of its + contributor version. + </para> + + <para> + In the following three paragraphs, a "patent license" is any + express agreement or commitment, however denominated, not to + enforce a patent (such as an express permission to practice a + patent or covenant not to sue for patent infringement). To + "grant" such a patent license to a party means to make such an + agreement or commitment not to enforce a patent against the + party. + </para> + + <para> + If you convey a covered work, knowingly relying on a patent + license, and the Corresponding Source of the work is not + available for anyone to copy, free of charge and under the terms + of this License, through a publicly available network server or + other readily accessible means, then you must either (1) cause + the Corresponding Source to be so available, or (2) arrange to + deprive yourself of the benefit of the patent license for this + particular work, or (3) arrange, in a manner consistent with the + requirements of this License, to extend the patent license to + downstream recipients. "Knowingly relying" means you have + actual knowledge that, but for the patent license, your + conveying the covered work in a country, or your recipient's use + of the covered work in a country, would infringe one or more + identifiable patents in that country that you have reason to + believe are valid. + </para> + + <para> + If, pursuant to or in connection with a single transaction or + arrangement, you convey, or propagate by procuring conveyance + of, a covered work, and grant a patent license to some of the + parties receiving the covered work authorizing them to use, + propagate, modify or convey a specific copy of the covered work, + then the patent license you grant is automatically extended to + all recipients of the covered work and works based on it. + </para> + + <para> + A patent license is "discriminatory" if it does not include + within the scope of its coverage, prohibits the exercise of, or + is conditioned on the non-exercise of one or more of the rights + that are specifically granted under this License. You may not + convey a covered work if you are a party to an arrangement with + a third party that is in the business of distributing software, + under which you make payment to the third party based on the + extent of your activity of conveying the work, and under which + the third party grants, to any of the parties who would receive + the covered work from you, a discriminatory patent license (a) + in connection with copies of the covered work conveyed by you + (or copies made from those copies), or (b) primarily for and in + connection with specific products or compilations that contain + the covered work, unless you entered into that arrangement, or + that patent license was granted, prior to 28 March 2007. + </para> + + <para> + Nothing in this License shall be construed as excluding or + limiting any implied license or other defenses to infringement + that may otherwise be available to you under applicable patent + law. + </para> + + <para> + 12. No Surrender of Others' Freedom. + </para> + + <para> + If conditions are imposed on you (whether by court order, + agreement or otherwise) that contradict the conditions of this + License, they do not excuse you from the conditions of this + License. If you cannot convey a covered work so as to satisfy + simultaneously your obligations under this License and any other + pertinent obligations, then as a consequence you may not convey + it at all. For example, if you agree to terms that obligate you + to collect a royalty for further conveying from those to whom + you convey the Program, the only way you could satisfy both + those terms and this License would be to refrain entirely from + conveying the Program. + </para> + + <para> + 13. Use with the GNU Affero General Public License. + </para> + + <para> + Notwithstanding any other provision of this License, you have + permission to link or combine any covered work with a work + licensed under version 3 of the GNU Affero General Public + License into a single combined work, and to convey the resulting + work. The terms of this License will continue to apply to the + part which is the covered work, but the special requirements of + the GNU Affero General Public License, section 13, concerning + interaction through a network will apply to the combination as + such. + </para> + + <para> + 14. Revised Versions of this License. + </para> + + <para> + The Free Software Foundation may publish revised and/or new + versions of the GNU General Public License from time to time. + Such new versions will be similar in spirit to the present + version, but may differ in detail to address new problems or + concerns. + </para> + + <para> + Each version is given a distinguishing version number. If the + Program specifies that a certain numbered version of the GNU + General Public License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that numbered version or of any later version published by the + Free Software Foundation. If the Program does not specify a + version number of the GNU General Public License, you may choose + any version ever published by the Free Software Foundation. + </para> + + <para> + If the Program specifies that a proxy can decide which future + versions of the GNU General Public License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Program. + </para> + + <para> + Later license versions may give you additional or different + permissions. However, no additional obligations are imposed on + any author or copyright holder as a result of your choosing to + follow a later version. + </para> + + <para> + 15. Disclaimer of Warranty. + </para> + + <para> + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY + APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE + COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS + IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE + ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS + WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE + COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + </para> + + <para> + 16. Limitation of Liability. + </para> + + <para> + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN + WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO + MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE + LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, + INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR + INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS + OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY + YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH + ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + </para> + + <para> + 17. Interpretation of Sections 15 and 16. + </para> + + <para> + If the disclaimer of warranty and limitation of liability + provided above cannot be given local legal effect according to + their terms, reviewing courts shall apply local law that most + closely approximates an absolute waiver of all civil liability + in connection with the Program, unless a warranty or assumption + of liability accompanies a copy of the Program in return for a + fee. + </para> + + <para> + Bison Exception + </para> + + <para> + As a special exception, you may create a larger work that + contains part or all of the Bison parser skeleton and distribute + that work under terms of your choice, so long as that work isn't + itself a parser generator using the skeleton or a modified + version thereof as a parser skeleton. Alternatively, if you + modify or redistribute the parser skeleton itself, you may (at + your option) remove this special exception, which will cause the + skeleton and the resulting Bison output files to be licensed + under the GNU General Public License without this special + exception. + </para> + + <para> + This special exception was added by the Free Software Foundation + in version 2.2 of Bison. + </para> + <para> + END OF TERMS AND CONDITIONS + </para> + + </sect2> + + <sect2 id="licWix-Toolset"> + + <title>WiX Toolset License</title> + + <para> + The WiX toolset is released under the Microsoft Reciprocal + License (MS-RL). A reciprocal license is used to ensure that + others who build on the effort of the WiX community give back to + the WiX community. Specifically the license requires that fixes + and improvements to the WiX toolset must be published using the + same license. + </para> + + <para> + Sometimes the reciprocal license is incorrectly interpreted to + also apply to bundles, packages, and custom actions built using + the WiX toolset. The Outercurve Foundation has previously + provided this statement below to clarify which now the .NET + Foundation reaffirms: + </para> + + <blockquote> + <para> + The WiX toolset (WiX) is licensed under the Microsoft + Reciprocal License (MS-RL). The MS-RL governs the distribution + of the software licensed under it, as well as derivative + works, and incorporates the definition of a derivative work + provided in U.S. copyright law. OuterCurve Foundation (and the + .NET Foundation) does not view the installer packages + generated by WiX as falling within the definition of a + derivative work, merely because they are produced using WiX. + Thus, the installer packages generated by WiX will normally + fall outside the scope of the MS-RL, and any of your source + code, binaries, libraries, routines or other software + components that are incorporated in installer packages + generated by WiX can be governed by other licensing terms. + </para> + </blockquote> + + <para> + The full text of the MS-RL license is reproduced below. It can + also be found in the LICENSE.TXT file included with the source + code. + </para> + + <para> + Microsoft Reciprocal License (MS-RL) + </para> + + <para> + This license governs use of the accompanying software. If you + use the software, you accept this license. If you do not accept + the license, do not use the software. + </para> + + <orderedlist> + + <listitem> + <para> + Definitions. + </para> + + <para> + The terms "reproduce," "reproduction," "derivative works," + and "distribution" have the same meaning here as under U.S. + copyright law. A "contribution" is the original software, + or any additions or changes to the software. A + "contributor" is any person that distributes its + contribution under this license. "Licensed patents" are a + contributor's patent claims that read directly on its + contribution. disclaimer. + </para> + </listitem> + + <listitem> + <para> + Grant of Rights + </para> + + <orderedlist> + + <listitem> + <para> + Copyright Grant- Subject to the terms of this license, + including the license conditions and limitations in + section 3, each contributor grants you a + non-exclusive, worldwide, royalty-free copyright + license to reproduce its contribution, prepare + derivative works of its contribution, and distribute + its contribution or any derivative works that you + create. + </para> + </listitem> + + <listitem> + <para> + Patent Grant- Subject to the terms of this license, + including the license conditions and limitations in + section 3, each contributor grants you a + non-exclusive, worldwide, royalty-free license under + its licensed patents to make, have made, use, sell, + offer for sale, import, and/or otherwise dispose of + its contribution in the software or derivative works + of the contribution in the software. + </para> + </listitem> + + </orderedlist> + + </listitem> + + <listitem> + <para> + Conditions and Limitations + </para> + + <orderedlist> + + <listitem> + <para> + Reciprocal Grants- For any file you distribute that + contains code from the software (in source code or + binary format), you must provide recipients the source + code to that file along with a copy of this license, + which license will govern that file. You may license + other files that are entirely your own work and do not + contain code from the software under any terms you + choose. + </para> + </listitem> + + <listitem> + <para> + No Trademark License- This license does not grant you + rights to use any contributors' name, logo, or + trademarks. + </para> + </listitem> + + <listitem> + <para> + If you bring a patent claim against any contributor + over patents that you claim are infringed by the + software, your patent license from such contributor to + the software ends automatically. + </para> + </listitem> + + <listitem> + <para> + If you distribute any portion of the software, you + must retain all copyright, patent, trademark, and + attribution notices that are present in the software. + </para> + </listitem> + + <listitem> + <para> + If you distribute any portion of the software in + source code form, you may do so only under this + license by including a complete copy of this license + with your distribution. If you distribute any portion + of the software in compiled or object code form, you + may only do so under a license that complies with this + license. + </para> + </listitem> + + <listitem> + <para> + The software is licensed "as-is." You bear the risk of + using it. The contributors give no express warranties, + guarantees or conditions. You may have additional + consumer rights under your local laws which this + license cannot change. To the extent permitted under + your local laws, the contributors exclude the implied + warranties of merchantability, fitness for a + particular purpose and non-infringement. + </para> + </listitem> + + </orderedlist> + + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="licXFree86"> + + <title>XFree86 License (variant 1)</title> + + <para> + Copyright (C) 1994-2003 The XFree86 Project, Inc. All Rights + Reserved. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE XFREE86 PROJECT BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN + ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR + IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS + IN THE SOFTWARE. + </para> + + <para> + Except as contained in this notice, the name of the XFree86 + Project shall not be used in advertising or otherwise to promote + the sale, use or other dealings in this Software without prior + written authorization from the XFree86 Project. + </para> + + </sect2> + + <sect2 id="licXFree86-v2"> + + <title>XFree86 License (variant 2)</title> + + <para> + Copyright 1997 by The XFree86 Project, Inc. + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of the XFree86 Project, Inc. not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. The + Xfree86 Project, Inc. makes no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + <para> + THE XFREE86 PROJECT, INC. DISCLAIMS ALL WARRANTIES WITH REGARD + TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL OREST ZBOROWSKI + OR DAVID WEXELBLAT BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licCereal"> + + <title>Cereal License</title> + + <para> + Copyright (c) 2013-2022, Randolph Voorhies, Shane Grant + All rights reserved. + </para> + + <para> + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are met: + </para> + + <itemizedlist> + + <listitem> + <para> + Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. + </para> + </listitem> + + <listitem> + <para> + Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials + provided with the distribution. + </para> + </listitem> + + <listitem> + <para> + Neither the name of the copyright holder nor the names of + its contributors may be used to endorse or promote products + derived from this software without specific prior written + permission. + </para> + </listitem> + + </itemizedlist> + + <para> + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND + CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR + CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED + AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING + IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF + THE POSSIBILITY OF SUCH DAMAGE. + </para> + + </sect2> + + <sect2 id="licX-KeithPackard1"> + + <title>Keith Packard License</title> + + <para> + Copyright (c) 2001, 2003 Keith Packard + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Keith Packard not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. Keith Packard makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-DRI2"> + + <title>X Direct Rendering Infrastructure (DRI) 2 Extension License</title> + + <para> + Copyright (c) 2007 Red Hat, Inc. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, and/or sell copies of + the Software, and to permit persons to whom the Software is + furnished to do so, provided that the above copyright notice(s) + and this permission notice appear in all copies of the Soft- + ware and that both the above copyright notice(s) and this + permission notice appear in supporting documentation. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE + COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE + FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL + DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR + OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE + USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + <para> + Except as contained in this notice, the name of a copyright + holder shall not be used in advertising or otherwise to promote + the sale, use or other dealings in this Software without prior + written authorization of the copyright holder. + </para> + + <para> + Authors: + Kristian Høgsberg (krh@redhat.com) + </para> + + </sect2> + + <sect2 id="licX-NCD-DEC"> + + <title>Network Computing Devices and DEC License</title> + + <para> + Copyright 1990, 1991 Network Computing Devices; Portions + Copyright 1987 by Digital Equipment Corporation + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the names of Network Computing Devices or Digital not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. Network + Computing Devices and Digital make no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + <para> + NETWORK COMPUTING DEVICES AND DIGITAL DISCLAIM ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL NETWORK + COMPUTING DEVICES OR DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT + OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING + FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF + CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR + IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licMIT-OpenGroup"> + + <title>MIT Open Group Variant License</title> + + <para> + Copyright 1989, 1990, 1991, 1998 The Open Group + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation. + </para> + + <para> + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR + ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF + CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. + </para> + + <para> + Except as contained in this notice, the name of The Open Group + shall not be used in advertising or otherwise to promote the + sale, use or other dealings in this Software without prior + written authorization from The Open Group. + </para> + + </sect2> + + <sect2 id="licX-DEC1"> + + <title>Digital Equipment Corporation License (variant 1)</title> + + <para> + Copyright 1987 by Digital Equipment Corporation, Maynard, + Massachusetts. All Rights Reserved + </para> + + <para> + Permission to use, copy, modify, and distribute this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appear in all + copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the name of + Digital not be used in advertising or publicity pertaining to + distribution of the software without specific, written prior + permission. + </para> + + <para> + DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, + IN NO EVENT SHALL DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-DEC2"> + + <title>Digital Equipment Corporation License (variant 2)</title> + + <para> + Copyright (c) 1996 Digital Equipment Corporation, Maynard, + Massachusetts. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software. + </para> + + <para> + The above copyright notice and this permission notice shall be included in + all copies or substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL DIGITAL EQUIPMENT + CORPORATION BE LIABLE FOR ANY CLAIM, DAMAGES, INCLUDING, BUT NOT + LIMITED TO CONSEQUENTIAL OR INCIDENTAL DAMAGES, OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, + ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. + </para> + + <para> + Except as contained in this notice, the name of Digital + Equipment Corporation shall not be used in advertising or + otherwise to promote the sale, use or other dealings in this + Software without prior written authorization from Digital + Equipment Corporation. + </para> + + </sect2> + + <sect2 id="licX-DEC3"> + + <title>Digital Equipment Corporation License (variant 3)</title> + + <para> + Copyright 1997 Digital Equipment Corporation. All rights + reserved. + </para> + + <para> + This software is furnished under license and may be used and + copied only in accordance with the following terms and + conditions. Subject to these conditions, you may download, + copy, install, use, modify and distribute this software in + source and/or binary form. No title or ownership is transferred + hereby. + </para> + + <para> + 1) Any source code used, modified or distributed must reproduce + and retain this copyright notice and list of conditions as they + appear in the source file. + </para> + + <para> + 2) No right is granted to use any trade name, trademark, or logo + of Digital Equipment Corporation. Neither the "Digital Equipment + Corporation" name nor any trademark or logo of Digital Equipment + Corporation may be used to endorse or promote products derived + from this software without the prior written permission of + Digital Equipment Corporation. + </para> + + <para> + 3) This software is provided "AS-IS" and any express or implied + warranties, including but not limited to, any implied warranties + of merchantability, fitness for a particular purpose, or + non-infringement are disclaimed. In no event shall DIGITAL be + liable for any damages whatsoever, and in particular, DIGITAL + shall not be liable for special, indirect, consequential, or + incidental damages or damages for lost profits, loss of revenue + or loss of use, whether such damages arise in contract, + negligence, tort, under statute, in equity, at law or otherwise, + even if advised of the possibility of such damage. + </para> + + </sect2> + + <sect2 id="licX-DEC-Quarterdeck"> + + <title>Digital Equipment Corporation and QuarterDeck Office Systems License</title> + + <para> + Copyright 1987 by Digital Equipment Corporation, Maynard, + Massachusetts, Copyright 1994 Quarterdeck Office Systems. All + Rights Reserved + </para> + + <para> + Permission to use, copy, modify, and distribute this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appear in all + copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the names of + Digital and Quarterdeck not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. + </para> + + <para> + DIGITAL AND QUARTERDECK DISCLAIM ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS, IN NO EVENT SHALL DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT + OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS + OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE + OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE + OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-HP1"> + + <title>Hewlett-Packard License (variant 1)</title> + + <para> + Copyright 1989 by Hewlett-Packard Company, Palo Alto, + California. + </para> + + <para> + Permission to use, copy, modify, and distribute this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appear in all + copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the name of + Hewlett-Packard not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. + </para> + + <para> + HEWLETT-PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL HEWLETT-PACKARD BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-HP2"> + + <title>Hewlett-Packard License (variant 2)</title> + + <para> + Copyright (c) 1994, 1995 Hewlett-Packard Company + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL HEWLETT-PACKARD COMPANY BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN + ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR + IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + THE SOFTWARE. + </para> + + <para> + Except as contained in this notice, the name of the + Hewlett-Packard Company shall not be used in advertising or + otherwise to promote the sale, use or other dealings in this + Software without prior written authorization from the + Hewlett-Packard Company. + </para> + + </sect2> + + <sect2 id="licX-HP3"> + + <title>Hewlett-Packard License (variant 3)</title> + + <para> + Copyright 1986, 1987, 1988 by Hewlett-Packard Corporation + </para> + + <para> + Permission to use, copy, modify, and distribute this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appear in all + copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the name of + Hewlett-Packard not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. + </para> + + <para> + Hewlett-Packard makes no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + <para> + This software is not subject to any license of the American + Telephone and Telegraph Company or of the Regents of the + University of California. + </para> + + </sect2> + + <sect2 id="licX-HP4"> + + <title>Hewlett-Packard License (variant 4)</title> + + <para> + Copyright 1987 by Apollo Computer Inc., Chelmsford, + Massachusetts.; Copyright 1989 by Hewlett-Packard Company. All + Rights Reserved + </para> + + <para> + Permission to use, duplicate, change, and distribute this + software and its documentation for any purpose and without fee + is granted, provided that the above copyright notice appear in + such copy and that this copyright notice appear in all + supporting documentation, and that the names of Apollo Computer + Inc., the Hewlett-Packard Company, or the X Consortium not be + used in advertising or publicity pertaining to distribution of + the software without written prior permission. + </para> + + <para> + HEWLETT-PACKARD MAKES NO WARRANTY OF ANY KIND WITH REGARD TO + THIS SOFWARE, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED + WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE. Hewlett-Packard shall not be liable for errors + contained herein or direct, indirect, special, incidental or + consequential damages in connection with the furnishing, + performance, or use of this material. + </para> + + </sect2> + + <sect2 id="licX-SGI"> + + <title>Silicon Graphics License</title> + + <para> + Copyright (c) 1993, 1997 by Silicon Graphics Computer Systems, + Inc. + </para> + + <para> + Permission to use, copy, modify, and distribute this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appear in all + copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the name of + Silicon Graphics not be used in advertising or publicity + pertaining to distribution of the software without specific + prior written permission. Silicon Graphics makes no + representation about the suitability of this software for any + purpose. It is provided "as is" without any express or implied + warranty. + </para> + + <para> + SILICON GRAPHICS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL SILICON + GRAPHICS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL + DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR + OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE + USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-RandR"> + + <title>X Resize and Rotate Extension (RandR) License</title> + + <para> + Copyright (c) 2000 Compaq Computer Corporation; Copyright (c) + 2002 Hewlett-Packard Company; Copyright (c) 2006 Intel + Corporation; Copyright (c) 2008 Red Hat, Inc. + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of the copyright holders not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. The copyright holders make + no representations about the suitability of this software for + any purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO + THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE COPYRIGHT + HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL + DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR + OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE + USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-SuSE"> + + <title>SuSE License</title> + + <para> + Copyright (c) 2000 SuSE, Inc. + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of SuSE not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. SuSE makes no representations about + the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + <para> + SuSE DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, + IN NO EVENT SHALL SuSE BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-NCD1"> + + <title>Network Computing Devices (NCD) License (variant 1)</title> + + <para> + Copyright 1992 Network Computing Devices; Portions + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of NCD. not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. NCD. makes no representations about + the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + <para> + NCD. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, + IN NO EVENT SHALL NCD. BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-NCD2"> + + <title>Network Computing Devices (NCD) License (variant 2)</title> + + <para> + Copyright 1988, 1989, 1990, 1994 Network Computing Devices, Inc. + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name Network Computing Devices, Inc. not be used in + advertising or publicity pertaining to distribution of this + software without specific, written prior permission. + </para> + + <para> + THIS SOFTWARE IS PROVIDED `AS-IS'. NETWORK COMPUTING DEVICES, + INC., DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + INCLUDING WITHOUT LIMITATION ALL IMPLIED WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR + NONINFRINGEMENT. IN NO EVENT SHALL NETWORK COMPUTING DEVICES, + INC., BE LIABLE FOR ANY DAMAGES WHATSOEVER, INCLUDING SPECIAL, + INCIDENTAL OR CONSEQUENTIAL DAMAGES, INCLUDING LOSS OF USE, + DATA, OR PROFITS, EVEN IF ADVISED OF THE POSSIBILITY THEREOF, + AND REGARDLESS OF WHETHER IN AN ACTION IN CONTRACT, TORT OR + NEGLIGENCE, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-NCD3"> + + <title>Network Computing Devices (NCD) License (variant 3)</title> + + <para> + Copyright 1989 Network Computing Devices, Inc., Mountain View, California. + </para> + + <para> + Permission to use, copy, modify, and distribute this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appear in all + copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the name of + N.C.D. not be used in advertising or publicity pertaining to + distribution of the software without specific, written prior + permission. N.C.D. makes no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + </sect2> + + <sect2 id="licX-DEC-Olivetti"> + + <title>Digital Equipment Corporation and Olivetti Research Limited License</title> + + <para> + Copyright 1991,1993 by Digital Equipment Corporation, Maynard, + Massachusetts, and Olivetti Research Limited, Cambridge, + England. All Rights Reserved + </para> + + <para> + Permission to use, copy, modify, and distribute this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appear in all + copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the names of + Digital or Olivetti not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. + </para> + + <para> + DIGITAL AND OLIVETTI DISCLAIM ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL THEY BE LIABLE FOR ANY SPECIAL, + INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER + RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING + OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS + SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX11-Multi-party"> + + <title>X Consortium, DEC, Intergraph, Silicon Graphics, and Hewlett-Packard License</title> + + <para> + Copyright (c) 1989 X Consortium, Inc. and Digital Equipment + Corporation.; Copyright (c) 1992 X Consortium, Inc. and + Intergraph Corporation.; Copyright (c) 1993 X Consortium, Inc. + and Silicon Graphics, Inc.; Copyright (c) 1994, 1995 X + Consortium, Inc. and Hewlett-Packard Company. + </para> + + <para> + Permission to use, copy, modify, and distribute this + documentation for any purpose and without fee is hereby granted, + provided that the above copyright notice and this permission + notice appear in all copies. Digital Equipment Corporation, + Intergraph Corporation, Silicon Graphics, Hewlett-Packard, and + the X Consortium make no representations about the suitability + for any purpose of the information in this document. This + documentation is provided ``as is'' without express or implied + warranty. + </para> + + </sect2> + + <sect2 id="licX-Sun"> + + <title>Sun Microsystems License</title> + + <para> + Copyright 2007, 2008, 2009 Sun Microsystems, Inc. All rights + reserved. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, and/or sell copies of + the Software, and to permit persons to whom the Software is + furnished to do so, provided that the above copyright notice(s) + and this permission notice appear in all copies of the Software + and that both the above copyright notice(s) and this permission + notice appear in supporting documentation. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE + COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE + FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, + OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR + PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER + TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + PERFORMANCE OF THIS SOFTWARE. + </para> + + <para> + Except as contained in this notice, the name of a copyright + holder shall not be used in advertising or otherwise to promote + the sale, use or other dealings in this Software without prior + written authorization of the copyright holder. + </para> + + </sect2> + + <sect2 id="licX-Pardines-Kettenis"> + + <title>X libpciaccess Library License</title> + + <para> + Copyright (c) 2008 Juan Romero Pardines; Copyright (c) 2008 Mark Kettenis + </para> + + <para> + Permission to use, copy, modify, and distribute this software + for any purpose with or without fee is hereby granted, provided + that the above copyright notice and this permission notice + appear in all copies. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL + WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED + WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE + AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-libxshmfence"> + + <title>X libxshmfence License</title> + + <para> + Copyright (c) 2013 Keith Packard + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of the copyright holders not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. The copyright holders make + no representations about the suitability of this software for + any purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO + THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE COPYRIGHT + HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL + DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR + OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE + USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Mouse"> + + <title>X xf86-input-mouse driver License</title> + + <para> + Copyright 1990,91 by Thomas Roell, Dinkelscherben, Germany.; + Copyright 1993 by David Dawes <dawes@xfree86.org>; + Copyright 2002 by SuSE Linux AG, Author: Egbert Eich; Copyright + 1994-2002 by The XFree86 Project, Inc.; Copyright 2002 by Paul + Elliott + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the names of copyright holders not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. The copyright holders make + no representations about the suitability of this software for + any purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO + THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE COPYRIGHT + HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL + DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR + OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE + USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Yokota"> + + <title>Kazutaka YOKOTA License</title> + + <para> + Copyright 1998 by Kazutaka YOKOTA + <yokota@zodiac.mech.utsunomiya-u.ac.jp> + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Kazutaka YOKOTA not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. Kazutaka YOKOTA makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + KAZUTAKA YOKOTA DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL KAZUTAKA YOKOTA BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Connectiva"> + + <title>Conectiva License</title> + + <para> + Copyright (c) 2000 by Conectiva S.A. (http://www.conectiva.com) + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL CONECTIVA LINUX BE LIABLE + FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. + </para> + + <para> + Except as contained in this notice, the name of Conectiva Linux + shall not be used in advertising or otherwise to promote the + sale, use or other dealings in this Software without prior + written authorization from Conectiva Linux. + </para> + + </sect2> + + <sect2 id="licX-RedHat-SuSE"> + + <title>Red Hat and SuSE License</title> + + <para> + Copyright © 2008 Red Hat, Inc. Partly based on code Copyright © + 2000 SuSE, Inc. + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Red Hat not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. Red Hat makes no representations + about the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + <para> + Red Hat DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, + IN NO EVENT SHALL Red Hat BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of SuSE not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. SuSE makes no representations about + the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + <para> + SuSE DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, + IN NO EVENT SHALL SuSE BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-RedHat"> + + <title>Red Hat License</title> + + <para> + Copyright (c) 2006 Red Hat, Inc. (C) Copyright 1998-1999 + Precision Insight, Inc., Cedar Park, Texas. All Rights Reserved. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sub license, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice (including + the next paragraph) shall be included in all copies or + substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NON-INFRINGEMENT. IN NO EVENT SHALL RED HAT, INC, OR PRECISION + INSIGHT AND/OR THEIR SUPPLIERS BE LIABLE FOR ANY CLAIM, DAMAGES + OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE + SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX11-RedHat"> + + <title>X Consortium and Red Hat License</title> + + <para> + Copyright (c) 1995 X Consortium Copyright 2004 Red Hat Inc., + Durham, North Carolina. All Rights Reserved. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation on the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NON-INFRINGEMENT. IN NO EVENT SHALL RED HAT, THE X CONSORTIUM, + AND/OR THEIR SUPPLIERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, + ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. + </para> + + <para> + Except as contained in this notice, the name of the X Consortium + shall not be used in advertising or otherwise to promote the + sale, use or other dealings in this Software without prior + written authorization from the X Consortium. + </para> + + </sect2> + + <sect2 id="licX-PrecisionInsight"> + + <title>Precision Insight License</title> + + <para> + Copyright 1998-2000 Precision Insight, Inc., Cedar Park, Texas.; + Copyright 2000 VA Linux Systems, Inc.; Copyright (c) 2002, 2008, + 2009 Apple Computer, Inc.; Copyright (c) 2003-2004 Torrey T. + Lyons.; All Rights Reserved. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sub license, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice (including + the next paragraph) shall be included in all copies or + substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NON-INFRINGEMENT. IN NO EVENT SHALL PRECISION INSIGHT AND/OR + ITS SUPPLIERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, + ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-VALinux-IBM"> + + <title>VA Linux and IBM License</title> + + <para> + (C) Copyright IBM Corporation 2003 All Rights Reserved. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation on the rights to use, + copy, modify, merge, publish, distribute, sub license, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice (including + the next paragraph) shall be included in all copies or + substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NON-INFRINGEMENT. IN NO EVENT SHALL VA LINUX SYSTEM, IBM AND/OR + THEIR SUPPLIERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, + ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-IBM"> + + <title>IBM License</title> + + <para> + (C) Copyright IBM Corporation 2004-2005 All Rights Reserved. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sub license, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice (including + the next paragraph) shall be included in all copies or + substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NON-INFRINGEMENT. IN NO EVENT SHALL IBM, AND/OR THEIR SUPPLIERS + BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN + AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF + OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS + IN THE SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-MetroLink1"> + + <title>Metro Link License (variant 1)</title> + + <para> + Copyright (c) 1997 Metro Link Incorporated + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sub license, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE + FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. + </para> + + <para> + Except as contained in this notice, the name of the Metro Link + shall not be used in advertising or otherwise to promote the + sale, use or other dealings in this Software without prior + written authorization from Metro Link. + </para> + + </sect2> + + <sect2 id="licX-MetroLink2"> + + <title>Metro Link License (variant 2)</title> + + <para> + Copyright 1995-1998 by Metro Link, Inc.; Copyright (c) 1997 + Matthieu Herrb + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Metro Link, Inc. not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. Metro Link, Inc. makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + METRO LINK, INC. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL METRO LINK, INC. BE LIABLE FOR + ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-MetroLink3"> + + <title>Metro Link License (variant 3)</title> + + <para> + Copyright 1998 by Metro Link Incorporated + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Metro Link Incorporated not be used in advertising + or publicity pertaining to distribution of the software without + specific, written prior permission. Metro Link Incorporated + makes no representations about the suitability of this software + for any purpose. It is provided "as is" without express or + implied warranty. + </para> + + <para> + METRO LINK INCORPORATED DISCLAIMS ALL WARRANTIES WITH REGARD TO + THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL METRO LINK + INCORPORATED BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-NVIDIA"> + + <title>NVIDIA License</title> + + <para> + Copyright (c) 2001, Andy Ritger aritger@nvidia.com All rights + reserved. + </para> + + <para> + Redistribution and use in source and binary forms, with or + without modification, are permitted provided that the following + conditions are met: + </para> + + <para> + o Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + </para> + + <para> + o Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + </para> + + <para> + o Neither the name of NVIDIA nor the names of its contributors + may be used to endorse or promote products derived from this + software without specific prior written permission. + </para> + + <para> + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND + CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE + LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, + OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, + OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR + TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY + OF SUCH DAMAGE. + </para> + + </sect2> + + <sect2 id="licX-Vrije"> + + <title>Vrije Universiteit License</title> + + <para> + Copyright 1992 Vrije Universiteit, The Netherlands + </para> + + <para> + Permission to use, copy, modify, and distribute this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appear in all + copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the name of + the Vrije Universiteit not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. The Vrije Universiteit makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + The Vrije Universiteit DISCLAIMS ALL WARRANTIES WITH REGARD TO + THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL The Vrije + Universiteit BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Concurrent"> + + <title>Concurrent Computer Corporation License</title> + + <para> + Copyright 1998 by Concurrent Computer Corporation + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Concurrent Computer Corporation not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. Concurrent + Computer Corporation makes no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + <para> + CONCURRENT COMPUTER CORPORATION DISCLAIMS ALL WARRANTIES WITH + REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL CONCURRENT + COMPUTER CORPORATION BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Nokia"> + + <title>Nokia License</title> + + <para> + Copyright (c) 2004 Nokia + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Nokia not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. Nokia makes no representations about + the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + <para> + NOKIA DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, + IN NO EVENT SHALL NOKIA BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Adobe"> + + <title>Adobe License</title> + + <para> + (c)Copyright 1988,1991 Adobe Systems Incorporated. All rights + reserved. + </para> + + <para> + Permission to use, copy, modify, distribute, and sublicense this + software and its documentation for any purpose and without fee + is hereby granted, provided that the above copyright notices + appear in all copies and that both those copyright notices and + this permission notice appear in supporting documentation and + that the name of Adobe Systems Incorporated not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. No + trademark license to use the Adobe trademarks is hereby granted. + If the Adobe trademark "Display PostScript"(tm) is used to + describe this software, its functionality or for any other + purpose, such use shall be limited to a statement that this + software works in conjunction with the Display PostScript + system. Proper trademark attribution to reflect Adobe's + ownership of the trademark shall be given whenever any such + reference to the Display PostScript system is made. + </para> + + <para> + ADOBE MAKES NO REPRESENTATIONS ABOUT THE SUITABILITY OF THE SOFTWARE FOR ANY + PURPOSE. IT IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY. ADOBE + DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON- + INFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL ADOBE BE LIABLE TO YOU + OR ANY OTHER PARTY FOR ANY SPECIAL, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY + DAMAGES WHATSOEVER WHETHER IN AN ACTION OF CONTRACT,NEGLIGENCE, STRICT + LIABILITY OR ANY OTHER ACTION ARISING OUT OF OR IN CONNECTION WITH THE USE OR + PERFORMANCE OF THIS SOFTWARE. ADOBE WILL NOT PROVIDE ANY TRAINING OR OTHER + SUPPORT FOR THE SOFTWARE. + </para> + + <para> + Adobe, PostScript, and Display PostScript are trademarks of Adobe Systems + Incorporated which may be registered in certain jurisdictions. + </para> + + </sect2> + + <sect2 id="licX-UC"> + + <title>University of California License (variant 1)</title> + + <para> + Copyright (c) 1987 by the Regents of the University of California + </para> + + <para> + Permission to use, copy, modify, and distribute this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appear in all + copies. The University of California makes no representations + about the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + </sect2> + + <sect2 id="licX-UC2"> + + <title>University of California License (variant 2)</title> + + <para> + Copyright (c) 1989, 1990, 1993, 1994 The Regents of the + University of California. All rights reserved. + </para> + + <para> + This code is derived from software contributed to Berkeley by + Chris Torek. + </para> + + <para> + This code is derived from software contributed to Berkeley by + Michael Rendell of Memorial University of Newfoundland. + </para> + + <para> + Redistribution and use in source and binary forms, with or + without modification, are permitted provided that the following + conditions are met: + </para> + + <para> + 1. Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. + </para> + + <para> + 2. Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + </para> + + <para> + 4. Neither the name of the University nor the names of its + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + </para> + + <para> + THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS + IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT + SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF + THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + SUCH DAMAGE. + </para> + + </sect2> + + <sect2 id="licX-OMRON-DG"> + + <title>OMRON Corporation and Data General Corporation License</title> + + <para> + Copyright 1992, 1993 Data General Corporation; Copyright 1992, + 1993 OMRON Corporation + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + neither the name OMRON or DATA GENERAL be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission of the party whose name is to + be used. Neither OMRON or DATA GENERAL make any representation + about the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + <para> + OMRON AND DATA GENERAL EACH DISCLAIM ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, + IN NO EVENT SHALL OMRON OR DATA GENERAL BE LIABLE FOR ANY SPECIAL, INDIRECT + OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER + TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE + OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Legacy1"> + + <title>X11 Legacy License (variant 1)</title> + + <para> + Copyright (c) 1999 Keith Packard; Copyright (c) 2000 Compaq + Computer Corporation; Copyright (c) 2002 MontaVista Software + Inc.; Copyright (c) 2005 OpenedHand Ltd.; Copyright (c) 2006 + Nokia Corporation + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of the authors and/or copyright holders not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. The + authors and/or copyright holders make no representations about + the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + <para> + THE AUTHORS AND/OR COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE AUTHORS + AND/OR COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Legacy2"> + + <title>X11 Legacy License (variant 2)</title> + + <para> + Copyright 1990,91 by Thomas Roell, Dinkelscherben, Germany; + Copyright 1993 by David Wexelblat <dwex@goblin.org>; + Copyright 1999 by David Holland <davidh@iquest.net>; + Copyright (c) 2000 Compaq Computer Corporation; Copyright (c) + 2002 Hewlett-Packard Company; Copyright (c) 2004, 2005 Red Hat, + Inc.; Copyright (c) 2004 Nicholas Miell; Copyright (c) 2005 + Trolltech AS; Copyright (c) 2006 Intel Corporation; Copyright + (c) 2006-2007 Keith Packard; Copyright (c) 2008 Red Hat, Inc; + Copyright (c) 2008 George Sapountzis <gsap7@yahoo.gr>; + Copyright (c) 2000 Keith Packard, member of The XFree86 Project, + Inc.; 2005 Lars Knoll & Zack Rusin, Trolltech + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of the copyright holders not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. The copyright holders make + no representations about the suitability of this software for + any purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO + THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE COPYRIGHT + HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL + DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR + OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE + USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Legacy3"> + + <title>X11 Legacy License (variant 3)</title> + + <para> + Copyright 1987, 1998 The Open Group; Copyright (c) 1998-1999, + 2001 The XFree86 Project, Inc.; Copyright (c) 2000 VA Linux + Systems, Inc.; Copyright (c) 2000, 2001 Nokia Home + Communications; Copyright (c) 2007, 2008 Red Hat, Inc.; All + rights reserved. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, and/or sell copies of + the Software, and to permit persons to whom the Software is + furnished to do so, provided that the above copyright notice(s) + and this permission notice appear in all copies of the Software + and that both the above copyright notice(s) and this permission + notice appear in supporting documentation. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE + COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE + FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, + OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR + PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER + TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + PERFORMANCE OF THIS SOFTWARE. + </para> + + <para> + Except as contained in this notice, the name of a copyright + holder shall not be used in advertising or otherwise to promote + the sale, use or other dealings in this Software without prior + written authorization of the copyright holder. + </para> + + </sect2> + + <sect2 id="licX-Legacy4"> + + <title>X11 Legacy License (variant 4)</title> + + <para> + Copyright 1996 by Thomas E. Dickey <dickey@clark.net> All + Rights Reserved + </para> + + <para> + Permission to use, copy, modify, and distribute this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appear in all + copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the name of + the above listed copyright holder(s) not be used in advertising + or publicity pertaining to distribution of the software without + specific, written prior + </para> + + <para> + THE ABOVE LISTED COPYRIGHT HOLDER(S) DISCLAIM ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE ABOVE + LISTED COPYRIGHT HOLDER(S) BE LIABLE FOR ANY SPECIAL, INDIRECT + OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING + FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF + CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR + IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Legacy5"> + + <title>X11 Legacy License (variant 5)</title> + + <para> + Copyright 1998-1999 Precision Insight, Inc., Cedar Park, Texas.; + Copyright (c) 2001 Andreas Monitzer.; Copyright (c) 2001-2004 + Greg Parker.; Copyright (c) 2001-2004 Torrey T. Lyons; Copyright + (c) 2002-2003 Apple Computer, Inc.; Copyright (c) 2004-2005 + Alexander Gottwald; Copyright (c) 2002-2009 Apple Inc.; + Copyright (c) 2007 Jeremy Huddleston; All Rights Reserved. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE ABOVE LISTED COPYRIGHT + HOLDER(S) BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, + WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR + OTHER DEALINGS IN THE SOFTWARE. + </para> + + <para> + Except as contained in this notice, the name(s) of the above + copyright holders shall not be used in advertising or otherwise + to promote the sale, use or other dealings in this Software + without prior written authorization. + </para> + + </sect2> + + <sect2 id="licX-Legacy6"> + + <title>X11 Legacy License (variant 6)</title> + + <para> + Copyright (C) 1999,2000 by Eric Sunshine + <sunshine@sunshineco.com>; Copyright (C) 2001-2005 by + Thomas Winischhofer, Vienna, Austria.; All rights reserved. + </para> + + <para> + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are met: + </para> + + <para> + 1. Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. + </para> + + <para> + 2. Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + </para> + + <para> + 3. The name of the author may not be used to endorse or promote + products derived from this software without specific prior + written permission. + </para> + + <para> + THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY + EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, + THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A + PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR + BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED + TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING + IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF + THE POSSIBILITY OF SUCH DAMAGE. + </para> + + </sect2> + + <sect2 id="licX-Legacy7"> + + <title>X11 Legacy License (variant 7)</title> + + <para> + Copyright (C) 2005 Bogdan D. bogdand@users.sourceforge.net + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY + CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF + CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. + </para> + + <para> + Except as contained in this notice, the name of the author shall + not be used in advertising or otherwise to promote the sale, use + or other dealings in this Software without prior written + authorization from the author. + </para> + + </sect2> + + <sect2 id="licX-Legacy8"> + + <title>X11 Legacy License (variant 8)</title> + + <para> + Copyright (c) 2002 David Dawes + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR + ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF + CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. + </para> + + <para> + Except as contained in this notice, the name of the author(s) + shall not be used in advertising or otherwise to promote the + sale, use or other dealings in this Software without prior + written authorization from the author(s). + </para> + + </sect2> + + <sect2 id="licX-Legacy9"> + + <title>X11 Legacy License (variant 9)</title> + + <para> + Copyright (C) 1996-1999 SciTech Software, Inc.; Copyright (C) + David Mosberger-Tang; Copyright (C) 1999 Egbert Eich; Copyright + (C) 2008 Bart Trojanowski, Symbio Technologies, LLC + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of the authors not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. The authors makes no representations + about the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + <para> + THE AUTHORS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Legacy10"> + + <title>X11 Legacy License (variant 10)</title> + + <para> + Copyright 2005-2006 Luc Verhaegen. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) OR + AUTHOR(S) BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, + WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR + OTHER DEALINGS IN THE SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Legacy11"> + + <title>X11 Legacy License (variant 11)</title> + + <para> + Copyright 1995 by Robin Cutshaw <robin@XFree86.Org>; + Copyright 2000 by Egbert Eich; Copyright 2002 by David Dawes + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the names of the above listed copyright holder(s) not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. The above + listed copyright holder(s) make(s) no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + <para> + THE ABOVE LISTED COPYRIGHT HOLDER(S) DISCLAIM(S) ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE ABOVE + LISTED COPYRIGHT HOLDER(S) BE LIABLE FOR ANY SPECIAL, INDIRECT + OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING + FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF + CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR + IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Legacy12"> + + <title>X11 Legacy License (variant 12)</title> + + <para> + Copyright 1990, 1991 by Thomas Roell, Dinkelscherben, Germany; Copyright 1992 by David Dawes <dawes@XFree86.org>; Copyright 1992 by Jim Tsillas <jtsilla@damon.ccs.northeastern.edu>; Copyright 1992 by Rich Murphey <Rich@Rice.edu>; Copyright 1992 by Robert Baron <Robert.Baron@ernst.mach.cs.cmu.edu>; Copyright 1992 by Orest Zborowski <obz@eskimo.com>; Copyright 1993 by Vrije Universiteit, The Netherlands; Copyright 1993 by David Wexelblat <dwex@XFree86.org>; Copyright 1994, 1996 by Holger Veit <Holger.Veit@gmd.de>; Copyright 1997 by Takis Psarogiannakopoulos <takis@dpmms.cam.ac.uk>; Copyright 1994-2003 by The XFree86 Project, Inc + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the names of the above listed copyright holders not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. The above + listed copyright holders make no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + <para> + THE ABOVE LISTED COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH + REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE ABOVE LISTED + COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Legacy13"> + + <title>X11 Legacy License (variant 13)</title> + + <para> + Copyright (C) 2000 Keith Packard; 2004 Eric Anholt; 2005 Zack Rusin + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of copyright holders not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. Copyright holders make no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO + THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE COPYRIGHT + HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL + DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR + OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE + USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Legacy14"> + + <title>X11 Legacy License (variant 14)</title> + + <para> + (C) Copyright IBM Corporation 2002-2007 All Rights Reserved. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation on the rights to use, + copy, modify, merge, publish, distribute, sub license, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice (including + the next paragraph) shall be included in all copies or + substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NON-INFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDERS + AND/OR THEIR SUPPLIERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, + ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that this permission notice appear in + supporting documentation. This permission notice shall be + included in all copies or substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY + CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF + CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-DavorMatic"> + + <title>Davor Matic License</title> + + <para> + Copyright 1993 by Davor Matic + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation. Davor + Matic makes no representations about the suitability of this + software for any purpose. It is provided "as is" without + express or implied warranty. + </para> + + </sect2> + + <sect2 id="licX-HaroldHuntII"> + + <title>Harold L Hunt II License</title> + + <para> + Copyright (C) 2001-2004 Harold L Hunt II All Rights Reserved.; + Copyright (C) Colin Harrison 2005-2008 + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL HAROLD L HUNT II BE LIABLE + FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. + </para> + + <para> + Except as contained in this notice, the name of Harold L Hunt II + shall not be used in advertising or otherwise to promote the + sale, use or other dealings in this Software without prior + written authorization from Harold L Hunt II. + </para> + + </sect2> + + <sect2 id="licX-Roell"> + + <title>Thomas Roell License</title> + + <para> + Copyright 1990,91 by Thomas Roell, Dinkelscherben, Germany. + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Thomas Roell not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. Thomas Roell makes no representations + about the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + <para> + THOMAS ROELL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL THOMAS ROELL BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Roell-Wexelblat"> + + <title>Thomas Roell and David Wexelblat License</title> + + <para> + Copyright 1990,91 by Thomas Roell, Dinkelscherben, Germany; + Copyright 1993 by David Wexelblat <dwex@goblin.org> + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the names of Thomas Roell and David Wexelblat not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. Thomas + Roell and David Wexelblat makes no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + <para> + THOMAS ROELL AND DAVID WEXELBLAT DISCLAIMS ALL WARRANTIES WITH + REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THOMAS ROELL OR + DAVID WEXELBLAT BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Roell-SGCS"> + + <title>Thomas Roell and SGCS (Snitily Graphics Consulting Services) License</title> + + <para> + Copyright 1990,91,92,93 by Thomas Roell, Germany.; Copyright + 1991,92,93 by SGCS (Snitily Graphics Consulting Services), + USA. + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Thomas Roell nor SGCS be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. Thomas Roell nor SGCS makes + no representations about the suitability of this software for + any purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + THOMAS ROELL AND SGCS DISCLAIMS ALL WARRANTIES WITH REGARD TO + THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THOMAS ROELL OR + SGCS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL + DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR + OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE + USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Hourihane"> + + <title>Alan Hourihane License</title> + + <para> + Copyright 1998 by Alan Hourihane, Wigan, England.; Copyright + 2000-2002 by Alan Hourihane, Flint Mountain, North Wales. + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Alan Hourihane not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. Alan Hourihane makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + ALAN HOURIHANE DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL ALAN HOURIHANE BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Keithley"> + + <title>Kaleb S. Keithley License</title> + + <para> + Copyright 1995 Kaleb S. KEITHLEY + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. + IN NO EVENT SHALL Kaleb S. KEITHLEY BE LIABLE FOR ANY CLAIM, DAMAGES + OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, + ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR + OTHER DEALINGS IN THE SOFTWARE. + </para> + + <para> + Except as contained in this notice, the name of Kaleb S. + KEITHLEY shall not be used in advertising or otherwise to + promote the sale, use or other dealings in this Software without + prior written authorization from Kaleb S. KEITHLEY + </para> + </sect2> + + <sect2 id="licX-Herrb"> + + <title>Matthieu Herrb License</title> + + <para> + Copyright (c) 1997 Matthieu Herrb + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Matthieu Herrb not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. Matthieu Herrb makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + MATTHIEU HERRB DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO + EVENT SHALL MATTHIEU HERRB BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER + TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Eich"> + + <title>Egbert Eich License</title> + + <para> + Copyright 2004, Egbert Eich + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice shall be included in + all copies or substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + EGBERT EICH BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER + IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CON- + NECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + </para> + + <para> + Except as contained in this notice, the name of Egbert Eich + shall not be used in advertising or otherwise to promote the + sale, use or other dealings in this Software without prior + written authorization from Egbert Eich. + </para> + + </sect2> + + <sect2 id="licX-Wexelblat"> + + <title>David Wexelblat License</title> + + <para> + Copyright 1993 by David Wexelblat <dwex@goblin.org>; + Copyright 2005 by Kean Johnston <jkj@sco.com>; Copyright + 1993 by David McCullough <davidm@stallion.oz.au> + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of David Wexelblat not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. David Wexelblat makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + DAVID WEXELBLAT DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL DAVID WEXELBLAT BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Zborowski-Wexelblat"> + + <title>Orest Zborowski and David Wexelblat License</title> + + <para> + Copyright 1992 by Orest Zborowski <obz@Kodak.com>; + Copyright 1993 by David Wexelblat <dwex@goblin.org> + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the names of Orest Zborowski and David Wexelblat not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. Orest + Zborowski and David Wexelblat make no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + <para> + OREST ZBOROWSKI AND DAVID WEXELBLAT DISCLAIMS ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL OREST + ZBOROWSKI OR DAVID WEXELBLAT BE LIABLE FOR ANY SPECIAL, INDIRECT + OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING + FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF + CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR + IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Zborowski-Dawes"> + + <title>Orest Zborowski and David Dawes License</title> + + <para> + Copyright 1992 by Orest Zborowski <obz@Kodak.com>; + Copyright 1993 by David Dawes <dawes@xfree86.org> + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the names of Orest Zborowski and David Dawes not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. Orest + Zborowski and David Dawes make no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + <para> + OREST ZBOROWSKI AND DAVID DAWES DISCLAIMS ALL WARRANTIES WITH + REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL OREST ZBOROWSKI + OR DAVID DAWES BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Lepied"> + + <title>Frederic Lepied License</title> + + <para> + Copyright 1995-1999 by Frederic Lepied, France. + <fred@sugix.frmug.fr.net> + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby + granted without fee, provided that the above copyright notice + appear in all copies and that both that copyright notice + and this permission notice appear in supporting + documentation, and that the name of Frederic Lepied not + be used in advertising or publicity pertaining to distribution + of the software without specific, written prior + permission. Frederic Lepied makes no representations + about the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + <para> + FREDERIC LEPIED DISCLAIMS ALL WARRANTIES WITH REGARD TO + THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL FREDERIC + LEPIED BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF + CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT + OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS + SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Murphy-Wexelblat"> + + <title>Rich Murphey and David Wexelblat License</title> + + <para> + Copyright 1992 by Rich Murphey <Rich@Rice.edu>; Copyright + 1993 by David Wexelblat <dwex@goblin.org> + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the names of Rich Murphey and David Wexelblat not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. Rich + Murphey and David Wexelblat make no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + <para> + RICH MURPHEY AND DAVID WEXELBLAT DISCLAIM ALL WARRANTIES WITH + REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL RICH MURPHEY OR + DAVID WEXELBLAT BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Murphey-Dawes"> + + <title>Rich Murphey and David Dawes License</title> + + <para> + Copyright 1992 by Rich Murphey <Rich@Rice.edu>; Copyright + 1993 by David Dawes <dawes@xfree86.org> + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the names of Rich Murphey and David Dawes not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. Rich + Murphey and David Dawes make no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + <para> + RICH MURPHEY AND DAVID DAWES DISCLAIM ALL WARRANTIES WITH REGARD + TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL RICH MURPHEY OR + DAVID DAWES BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL + DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR + OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE + USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Carlsson"> + + <title>Anders Carlsson License</title> + + <para> + Copyright (c) 2003-2004 Anders Carlsson + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Anders Carlsson not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. Anders Carlsson makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + ANDERS CARLSSON DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL ANDERS CARLSSON BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Anholt"> + + <title>Eric Anholt License</title> + + <para> + Copyright (C) 2003 Anders Carlsson; Copyright (c) 2003-2004 Eric + Anholt; Copyright (c) 2004 Keith Packard + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Eric Anholt not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. Eric Anholt makes no representations + about the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + <para> + ERIC ANHOLT DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL ERIC ANHOLT BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Miller"> + + <title>Todd C. Miller License</title> + + <para> + Copyright (c) 1998 Todd C. Miller <Todd.Miller@courtesan.com> + </para> + + <para> + Permission to use, copy, modify, and distribute this software for any + purpose with or without fee is hereby granted, provided that the above + copyright notice and this permission notice appear in all copies. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS" AND TODD C. MILLER DISCLAIMS + ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT + SHALL TODD C. MILLER BE LIABLE FOR ANY SPECIAL, DIRECT, + INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER + RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING + OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS + SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Blundell"> + + <title>Philip Blundell License</title> + + <para> + Copyright (c) 2003-2004 Philip Blundell + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Philip Blundell not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. Philip Blundell makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + PHILIP BLUNDELL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL PHILIP BLUNDELL BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-AureleLF"> + + <title>Marc Aurele La France License</title> + + <para> + Copyright 1997-2004 by Marc Aurele La France (TSI @ UQV), + tsi@xfree86.org + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Marc Aurele La France not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. Marc Aurele La France makes + no representations about the suitability of this software for + any purpose. It is provided "as-is" without express or implied + warranty. + </para> + + <para> + MARC AURELE LA FRANCE DISCLAIMS ALL WARRANTIES WITH REGARD TO + THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL MARC AURELE LA + FRANCE BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL + DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR + OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE + USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Johnston"> + + <title>J. Kean Johnston License</title> + + <para> + Copyright 2001-2005 by J. Kean Johnston <jkj@sco.com> + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name J. Kean Johnston not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. J. Kean Johnston makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + J. KEAN JOHNSTON DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL J. KEAN JOHNSTON BE LIABLE FOR + ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Jelinek"> + + <title>Jakub Jelinek License</title> + + <para> + Copyright (C) 2000 Jakub Jelinek (jakub@redhat.com) + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL JAKUB JELINEK BE LIABLE FOR + ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF + CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Yasushi"> + + <title>UCHIYAMA Yasushi License</title> + + <para> + Copyright 1997,1998 by UCHIYAMA Yasushi + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of UCHIYAMA Yasushi not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. UCHIYAMA Yasushi makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + UCHIYAMA YASUSHI DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL UCHIYAMA YASUSHI BE LIABLE FOR + ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-OpenedHand"> + + <title>OpenedHand Ltd License</title> + + <para> + Copyright (c) 2007 OpenedHand Ltd + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of OpenedHand Ltd not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. OpenedHand Ltd makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + OpenedHand Ltd DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL OpenedHand Ltd BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Oracle"> + + <title>Oracle License</title> + + <para> + Copyright (c) 1991, Oracle and/or its affiliates. All rights + reserved. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + </para> + + <para> + The above copyright notice and this permission notice (including + the next paragraph) shall be included in all copies or + substantial portions of the Software. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT + HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, + WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR + OTHER DEALINGS IN THE SOFTWARE. + </para> + + </sect2> + + <sect2 id="licNVIDIA-Glslang"> + + <title>NVIDIA License for Glslang</title> + + <para> + Copyright (c) 2002, NVIDIA Corporation. + </para> + + <para> + NVIDIA Corporation("NVIDIA") supplies this software to you in + consideration of your agreement to the following terms, and your + use, installation, modification or redistribution of this NVIDIA + software constitutes acceptance of these terms. If you do not + agree with these terms, please do not use, install, modify or + redistribute this NVIDIA software. + </para> + + <para> + In consideration of your agreement to abide by the following + terms, and subject to these terms, NVIDIA grants you a personal, + non-exclusive license, under NVIDIA's copyrights in this + original NVIDIA software (the "NVIDIA Software"), to use, + reproduce, modify and redistribute the NVIDIA Software, with or + without modifications, in source and/or binary forms; provided + that if you redistribute the NVIDIA Software, you must retain + the copyright notice of NVIDIA, this notice and the following + text and disclaimers in all such redistributions of the NVIDIA + Software. Neither the name, trademarks, service marks nor logos + of NVIDIA Corporation may be used to endorse or promote products + derived from the NVIDIA Software without specific prior written + permission from NVIDIA. Except as expressly stated in this + notice, no other rights or licenses express or implied, are + granted by NVIDIA herein, including but not limited to any + patent rights that may be infringed by your derivative works or + by other works in which the NVIDIA Software may be incorporated. + No hardware is licensed hereunder. + </para> + + <para> + THE NVIDIA SOFTWARE IS BEING PROVIDED ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR + IMPLIED, INCLUDING WITHOUT LIMITATION, WARRANTIES OR CONDITIONS + OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, FITNESS FOR A + PARTICULAR PURPOSE, OR ITS USE AND OPERATION EITHER ALONE OR IN + COMBINATION WITH OTHER PRODUCTS. + </para> + + <para> + IN NO EVENT SHALL NVIDIA BE LIABLE FOR ANY SPECIAL, INDIRECT, + INCIDENTAL, EXEMPLARY, CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, LOST PROFITS; PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + INTERRUPTION) OR ARISING IN ANY WAY OUT OF THE USE, + REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION OF THE NVIDIA + SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, + TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN + IF NVIDIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + </para> + + </sect2> + + <sect2 id="licKhronos-Glslang"> + + <title>The Khronos Group Inc. License for Glslang</title> + + <para> + Copyright (c) 2014-2016 The Khronos Group Inc. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and/or associated + documentation files (the "Materials"), to deal in the Materials + without restriction, including without limitation the rights to + use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Materials, and to permit persons to + whom the Materials are furnished to do so, subject to the + following conditions: + </para> + + <para> + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Materials. + </para> + + <para> + MODIFICATIONS TO THIS FILE MAY MEAN IT NO LONGER ACCURATELY + REFLECTS KHRONOS STANDARDS. THE UNMODIFIED, NORMATIVE VERSIONS + OF KHRONOS SPECIFICATIONS AND HEADER INFORMATION ARE LOCATED AT + https://www.khronos.org/registry/ + </para> + + <para> + THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE + AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT + HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, + WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM,OUT OF OR IN CONNECTION WITH THE MATERIALS OR THE USE OR + OTHER DEALINGS The above copyright notice and this permission + notice shall be included in all copies or substantial portions + of the Materials. IN THE MATERIALS. + </para> + + </sect2> + + <sect2 id="licKhronos-EGL"> + + <title>The Khronos Group Inc. License for the EGL Registry Repository</title> + + <para> + Copyright (c) 2008-2018 The Khronos Group Inc. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and/or associated + documentation files (the "Materials"), to deal in the Materials + without restriction, including without limitation the rights to + use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Materials, and to permit persons to + whom the Materials are furnished to do so, subject to the + following conditions: + </para> + + <para> + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Materials. + </para> + + <para> + THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE + AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT + HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, + WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE MATERIALS OR THE USE OR + OTHER DEALINGS IN THE MATERIALS. + </para> + + </sect2> + + <sect2 id="licTpms"> + + <title>The IBM Corporation License for the libtpms library</title> + + <para> + Copyright IBM Corporation 2006 - 2011 All rights reserved; + Copyright IBM Corp. and others, 2012-2016 + </para> + + <para> + For the TPM 1.2 code and the library code the following license applies: + </para> + + <para> + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are + met: + Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + Neither the names of the IBM Corporation nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + </para> + + <para> + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + </para> + + <para> + For the TPM 2 code the following license and notices apply: + </para> + + <para> + Licenses and Notices + </para> + + <orderedlist> + + <listitem> + + <para> + Copyright Licenses: + </para> + + <itemizedlist> + + <listitem> + <para> + Trusted Computing Group (TCG) grants to the user of the source code in + this specification (the "Source Code") a worldwide, irrevocable, + nonexclusive, royalty free, copyright license to reproduce, create + derivative works, distribute, display and perform the Source Code and + derivative works thereof, and to grant others the rights granted herein. + </para> + </listitem> + + <listitem> + <para> + The TCG grants to the user of the other parts of the specification + (other than the Source Code) the rights to reproduce, distribute, + display, and perform the specification solely for the purpose of + developing products based on such documents. + </para> + </listitem> + + </itemizedlist> + + </listitem> + + <listitem> + <para> + Source Code Distribution Conditions: + </para> + + <itemizedlist> + + <listitem> + <para> + Redistributions of Source Code must retain the above copyright licenses, + this list of conditions and the following disclaimers. + </para> + </listitem> + + <listitem> + <para> + Redistributions in binary form must reproduce the above copyright + licenses, this list of conditions and the following disclaimers in the + documentation and/or other materials provided with the distribution. + </para> + </listitem> + + </itemizedlist> + + </listitem> + + <listitem> + <para> + Disclaimers: + </para> + + <itemizedlist> + + <listitem> + <para> + THE COPYRIGHT LICENSES SET FORTH ABOVE DO NOT REPRESENT ANY FORM OF + LICENSE OR WAIVER, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, WITH + RESPECT TO PATENT RIGHTS HELD BY TCG MEMBERS (OR OTHER THIRD PARTIES) + THAT MAY BE NECESSARY TO IMPLEMENT THIS SPECIFICATION OR OTHERWISE. + Contact TCG Administration (admin@trustedcomputinggroup.org) for + information on specification licensing rights available through TCG + membership agreements. + </para> + </listitem> + + <listitem> + <para> + THIS SPECIFICATION IS PROVIDED "AS IS" WITH NO EXPRESS OR IMPLIED + WARRANTIES WHATSOEVER, INCLUDING ANY WARRANTY OF MERCHANTABILITY OR + FITNESS FOR A PARTICULAR PURPOSE, ACCURACY, COMPLETENESS, OR + NONINFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS, OR ANY WARRANTY + OTHERWISE ARISING OUT OF ANY PROPOSAL, SPECIFICATION OR SAMPLE. + </para> + </listitem> + + <listitem> + <para> + Without limitation, TCG and its members and licensors disclaim all + liability, including liability for infringement of any proprietary + rights, relating to use of information in this specification and to the + implementation of this specification, and TCG disclaims all liability for + cost of procurement of substitute goods or services, lost profits, loss + of use, loss of data or any incidental, consequential, direct, indirect, + or special damages, whether under contract, tort, warranty or otherwise, + arising in any way out of use or reliance upon this specification or any + information herein. + </para> + </listitem> + + </itemizedlist> + </listitem> + </orderedlist> + + </sect2> + + </sect1> + +</appendix> diff --git a/doc/manual/en_US/user_Troubleshooting.xml b/doc/manual/en_US/user_Troubleshooting.xml new file mode 100644 index 00000000..4906fd48 --- /dev/null +++ b/doc/manual/en_US/user_Troubleshooting.xml @@ -0,0 +1,1938 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="Troubleshooting"> + + <title>Troubleshooting</title> + + <para> + This chapter provides answers to commonly asked questions. In order + to improve your user experience with &product-name;, it is + recommended to read this section to learn more about common pitfalls + and get recommendations on how to use the product. + </para> + + <sect1 id="ts_procs-tools"> + + <title>Procedures and Tools</title> + + <sect2 id="ts_categorize-isolate"> + + <title>Categorizing and Isolating Problems</title> + + <para> + More often than not, a virtualized guest behaves like a physical + system. Any problems that a physical machine would encounter, a + virtual machine will encounter as well. If, for example, + Internet connectivity is lost due to external issues, virtual + machines will be affected just as much as physical ones. + </para> + + <para> + If a true &product-name; problem is encountered, it helps to + categorize and isolate the problem first. Here are some of the + questions that should be answered before reporting a problem: + </para> + + <itemizedlist> + + <listitem> + <para> + Is the problem specific to a certain guest OS? Or a specific + release of a guest OS? Especially with Linux guest related + problems, the issue may be specific to a certain + distribution and version of Linux. + </para> + </listitem> + + <listitem> + <para> + Is the problem specific to a certain host OS? Problems are + usually not host OS specific, because most of the + &product-name; code base is shared across all supported + platforms, but especially in the areas of networking and USB + support, there are significant differences between host + platforms. Some GUI related issues are also host specific. + </para> + </listitem> + + <listitem> + <para> + Is the problem specific to certain host hardware? This + category of issues is typically related to the host CPU. + Because of significant differences between VT-x and AMD-V, + problems may be specific to one or the other technology. The + exact CPU model may also make a difference because different + CPUs support different features, which may affect certain + aspects of guest CPU operation. + </para> + </listitem> + + <listitem> + <para> + Is the problem specific to guest SMP? That is, is it related + to the number of virtual CPUs (VCPUs) in the guest? Using + more than one CPU usually significantly affects the internal + operation of a guest OS. + </para> + </listitem> + + <listitem> + <para> + Is the problem specific to the Guest Additions? In some + cases, this is obvious, such as a shared folders problem. In + other cases such as display problems, it may be less + obvious. If the problem is Guest Additions specific, is it + also specific to a certain version of the Guest Additions? + </para> + </listitem> + + <listitem> + <para> + Is the problem specific to a certain environment? Some + problems are related to a particular environment external to + the VM. This usually involves network setup. Certain + configurations of external servers such as DHCP or PXE may + expose problems which do not occur with other, similar + servers. + </para> + </listitem> + + <listitem> + <para> + Is the problem a regression? Knowing that an issue is a + regression usually makes it significantly easier to find the + solution. In this case, it is crucial to know which version + is affected and which is not. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="collect-debug-info"> + + <title>Collecting Debugging Information</title> + + <para> + For problem determination, it is often important to collect + debugging information which can be analyzed by &product-name; + support. This section contains information about what kind of + information can be obtained. + </para> + + <para> + Every time &product-name; starts up a VM, a so-called + <emphasis>release log file</emphasis> is created, containing + lots of information about the VM configuration and runtime + events. The log file is called <filename>VBox.log</filename> and + resides in the VM log file folder, which is + <filename>$HOME/VirtualBox + VMs/<replaceable>VM-name</replaceable>/Logs</filename> by + default. + </para> + + <para> + When starting a VM, the configuration file of the last run will + be renamed to <filename>.1</filename>, up to + <filename>.3</filename>. Sometimes when there is a problem, it + is useful to have a look at the logs. Also when requesting + support for &product-name;, supplying the corresponding log file + is mandatory. + </para> + + <para> + For convenience, for each virtual machine, &vbox-mgr; can show + these logs in a window. Select a virtual machine from the + machine list on the left and click + <emphasis role="bold">Logs</emphasis> in the machine tools menu. + </para> + + <para> + The release log file, <filename>VBox.log</filename>, contains a + wealth of diagnostic information, such as Host OS type and + version, &product-name; version and build. It also includes a + complete dump of the guest's configuration (CFGM), detailed + information about the host CPU type and supported features, + whether hardware virtualization is enabled, information about + VT-x/AMD-V setup, state transitions (such as creating, running, + paused, stopping), guest BIOS messages, Guest Additions + messages, device-specific log entries and, at the end of + execution, final guest state and condensed statistics. + </para> + + <para> + In case of crashes, it is very important to collect + <emphasis>crash dumps</emphasis>. This is true for both host and + guest crashes. For information about enabling core dumps on + Linux, Oracle Solaris, and macOS systems, refer to the following + core dump article on the &product-name; website: + </para> + + <para> + <ulink url="http://www.virtualbox.org/wiki/Core_dump" />. + </para> + + <para> + You can also use <command>VBoxManage debugvm</command> to create + a dump of a complete virtual machine. See + <xref linkend="vboxmanage-debugvm" />. + </para> + + <para> + For network related problems, it is often helpful to capture a + trace of network traffic. If the traffic is routed through an + adapter on the host, it is possible to use Wireshark or a + similar tool to capture the traffic there. However, this often + also includes a lot of traffic unrelated to the VM. + </para> + + <para> + &product-name; provides an ability to capture network traffic + only on a specific VM's network adapter. Refer to the following + network tracing article on the &product-name; website for + information on enabling this capture: + </para> + + <para> + <ulink url="http://www.virtualbox.org/wiki/Network_tips" />. + </para> + + <para> + The trace files created by &product-name; are in + <filename>.pcap</filename> format and can be easily analyzed + with Wireshark. + </para> + + </sect2> + + <sect2 id="ts_vboxbugreport"> + + <title>Using the VBoxBugReport Command to Collect Debug Information + Automatically</title> + + <para> + The <command>VBoxBugReport</command> command is used to collect + debug information automatically for an &product-name; + installation. This command can be useful when you need to gather + information to send to Oracle Support. + </para> + + <para> + The following examples show how to use + <command>VBoxBugReport</command>. + </para> + + <para> + By default, the command collects <command>VBoxSVC</command> + process logs, device settings, and global configuration data for + an &product-name; host. + </para> + +<screen>$ VBoxBugReport + ... + 0% - collecting VBoxSVC.log.10... + 7% - collecting VBoxSVC.log.9... + ... + 64% - collecting VBoxSVC.log.1... + 71% - collecting VBoxSVC.log... + 78% - collecting VirtualBox.xml... + 85% - collecting HostUsbDevices... + 92% - collecting HostUsbFilters... +100% - compressing... + +Report was written to '2019-03-26-13-32-02-bugreport.tgz'</screen> + + <para> + The results are saved as a compressed tar file archive in the + same directory where the command is run. + </para> + + <para> + To specify a different output file location: + </para> + +<screen>$ VBoxBugReport --output ~/debug/bug004.tgz</screen> + + <para> + To output all debug information to a single text file, rather + than a <filename>tgz</filename> file: + </para> + +<screen>$ VBoxBugReport --text</screen> + + <para> + To collect information for a specific VM, called + <literal>Windows_10</literal>: + </para> + +<screen>$ VBoxBugReport Windows_10</screen> + + <para> + This command collects machine settings, guest properties, and + log files for the specified VM. Global configuration information + for the host is also included. + </para> + + <para> + To collect information for several VMs, called + <literal>Windows_7</literal>, <literal>Windows_8</literal>, and + <literal>Windows_10</literal>: + </para> + +<screen>$ VBoxBugReport Windows_7 Windows_8 Windows_10</screen> + + <para> + To collect information for all VMs: + </para> + +<screen>$ VBoxBugReport --all</screen> + + <para> + To show a full list of the available command options, run + <command>VBoxBugReport --help</command>. + </para> + + </sect2> + + <sect2 id="ts_debugger"> + + <title>The Built-In VM Debugger</title> + + <para> + &product-name; includes a built-in VM debugger, which advanced + users may find useful. This debugger enables you to examine and, + to some extent, control the VM state. + </para> + + <warning> + <para> + Use the VM debugger at your own risk. There is no support for + it, and the following documentation is only made available for + advanced users with a very high level of familiarity with the + x86/AMD64 machine instruction set, as well as detailed + knowledge of the PC architecture. A degree of familiarity with + the internals of the guest OS in question may also be very + helpful. + </para> + </warning> + + <para> + The VM debugger is available in all regular production versions + of &product-name;, but it is disabled by default because the + average user will have little use for it. There are two ways to + access the debugger: + </para> + + <itemizedlist> + + <listitem> + <para> + Using a debugger console window displayed alongside the VM + </para> + </listitem> + + <listitem> + <para> + Using the <command>telnet</command> protocol on port 5000 + </para> + </listitem> + + </itemizedlist> + + <para> + The debugger can be enabled in the following ways: + </para> + + <itemizedlist> + + <listitem> + <para> + Start the VM directly using <command>VirtualBoxVM + --startvm</command>, with an additional + <option>--dbg</option>, <option>--debug</option>, or + <option>--debug-command-line</option> argument. See the + <command>VirtualBoxVM --help</command> command usage help + for details. + </para> + </listitem> + + <listitem> + <para> + Set the <literal>VBOX_GUI_DBG_ENABLED</literal> or + <literal>VBOX_GUI_DBG_AUTO_SHOW</literal> environment + variable to <literal>true</literal> before launching the + &product-name; process. Setting these variables, only their + presence is checked, is effective even when the first + &product-name; process is the VM selector window. VMs + subsequently launched from the selector will have the + debugger enabled. + </para> + </listitem> + + <listitem> + <para> + Set the <literal>GUI/Dbg/Enabled</literal> extra data item + to <literal>true</literal> before launching the VM. This can + be set globally or on a per VM basis. + </para> + </listitem> + + </itemizedlist> + + <para> + A new <emphasis role="bold">Debug</emphasis> menu entry is added + to the &product-name; application. This menu enables the user to + open the debugger console. + </para> + + <para> + The VM debugger command syntax is loosely modeled on Microsoft + and IBM debuggers used on DOS, OS/2, and Windows. Users familiar + with symdeb, CodeView, or the OS/2 kernel debugger will find the + &product-name; VM debugger familiar. + </para> + + <para> + The most important command is <command>help</command>. This will + print brief usage help for all debugger commands. The set of + commands supported by the VM debugger changes frequently and the + <command>help</command> command is always up-to-date. + </para> + + <para> + A brief summary of frequently used commands is as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <command>stop</command>: Stops the VM execution and enables + single stepping + </para> + </listitem> + + <listitem> + <para> + <command>g</command>: Continue VM execution + </para> + </listitem> + + <listitem> + <para> + <command>t</command>: Single step an instruction + </para> + </listitem> + + <listitem> + <para> + <command>rg</command>, <command>rh</command>, and + <command>r</command>: Print the guest, hypervisor, and + current registers + </para> + </listitem> + + <listitem> + <para> + <command>kg</command>, <command>kh</command>, and + <command>k</command>: Print the guest, hypervisor, and + current call stack + </para> + </listitem> + + <listitem> + <para> + <command>da</command>, <command>db</command>, + <command>dw</command>, <command>dd</command>, + <command>dq</command>: Print memory contents as ASCII, + bytes, words, dwords, and qwords + </para> + </listitem> + + <listitem> + <para> + <command>u</command>: Unassemble memory + </para> + </listitem> + + <listitem> + <para> + <command>dg</command>: Print the guest's GDT + </para> + </listitem> + + <listitem> + <para> + <command>di</command>: Print the guest's IDT + </para> + </listitem> + + <listitem> + <para> + <command>dl</command>: Print the guest's LDT + </para> + </listitem> + + <listitem> + <para> + <command>dt</command>: Print the guest's TSS + </para> + </listitem> + + <listitem> + <para> + <command>dp*</command>: Print the guest's page table + structures + </para> + </listitem> + + <listitem> + <para> + <command>bp</command> and <command>br</command>: Set a + normal and recompiler breakpoint + </para> + </listitem> + + <listitem> + <para> + <command>bl</command>: List breakpoints + </para> + </listitem> + + <listitem> + <para> + <command>bc</command>: Clear a breakpoint + </para> + </listitem> + + <listitem> + <para> + <command>writecore</command>: Write a VM core file to disk. + See <xref linkend="ts_guest-core-format" /> + </para> + </listitem> + + </itemizedlist> + + <para> + See the built-in <command>help</command> for other available + commands. + </para> + + <para> + The VM debugger supports symbolic debugging, although symbols + for guest code are often not available. For Oracle Solaris + guests, the <command>detect</command> command automatically + determines the guest OS version and locates kernel symbols in + guest's memory. Symbolic debugging is then available. For Linux + guests, the <command>detect</command> commands also determines + the guest OS version, but there are no symbols in the guest's + memory. Kernel symbols are available in the file + <filename>/proc/kallsyms</filename> on Linux guests. This file + must be copied to the host, for example using + <command>scp</command>. The <command>loadmap</command> debugger + command can be used to make the symbol information available to + the VM debugger. Note that the <filename>kallsyms</filename> + file contains the symbols for the currently loaded modules. If + the guest's configuration changes, the symbols will change as + well and must be updated. + </para> + + <para> + For all guests, a simple way to verify that the correct symbols + are loaded is the <command>k</command> command. The guest is + normally idling and it should be clear from the symbolic + information that the guest operating system's idle loop is being + executed. + </para> + + <para> + Another group of debugger commands is the set of + <command>info</command> commands. Running <command>info + help</command> provides complete usage information. The + information commands provide ad-hoc data pertinent to various + emulated devices and aspects of the VMM. There is no general + guideline for using the <command>info</command> commands, the + right command to use depends entirely on the problem being + investigated. Some of the <command>info</command> commands are + as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <command>cfgm</command>: Print a branch of the configuration + tree + </para> + </listitem> + + <listitem> + <para> + <command>cpuid</command>: Display the guest CPUID leaves + </para> + </listitem> + + <listitem> + <para> + <command>ioport</command>: Print registered I/O port ranges + </para> + </listitem> + + <listitem> + <para> + <command>mmio</command>: Print registered MMIO ranges + </para> + </listitem> + + <listitem> + <para> + <command>mode</command>: Print the current paging mode + </para> + </listitem> + + <listitem> + <para> + <command>pit</command>: Print the i8254 PIT state + </para> + </listitem> + + <listitem> + <para> + <command>pic</command>: Print the i8259A PIC state + </para> + </listitem> + + <listitem> + <para> + <command>ohci</command>, <command>ehci</command>, + <command>xhci</command>: Print a subset of the OHCI, EHCI, + and xHCI USB controller state + </para> + </listitem> + + <listitem> + <para> + <command>pcnet0</command>: Print the PCnet state + </para> + </listitem> + + <listitem> + <para> + <command>vgatext</command>: Print the contents of the VGA + framebuffer formatted as standard text mode + </para> + </listitem> + + <listitem> + <para> + <command>timers</command>: Print all VM timers + </para> + </listitem> + + </itemizedlist> + + <para> + The output of the <command>info</command> commands generally + requires in-depth knowledge of the emulated device or + &product-name; VMM internals. However, when used properly, the + information provided can be invaluable. + </para> + + </sect2> + + <sect2 id="ts_guest-core-format"> + + <title>VM Core Format</title> + + <para> + &product-name; uses the 64-bit ELF format for its VM core files + created by <command>VBoxManage debugvm</command>, see + <xref linkend="vboxmanage-debugvm" />. The VM core file contain + the memory and CPU dumps of the VM and can be useful for + debugging your guest OS. The 64-bit ELF object format + specification can be obtained at: + </para> + + <para> + <ulink url="http://downloads.openwatcom.org/ftp/devel/docs/elf-64-gen.pdf" />. + </para> + + <para> + The overall layout of the VM core format is as follows: + </para> + +<screen>[ ELF 64 Header] +[ Program Header, type PT_NOTE ] + → offset to COREDESCRIPTOR +[ Program Header, type PT_LOAD ] - one for each contiguous physical memory range + → Memory offset of range + → File offset +[ Note Header, type NT_VBOXCORE ] +[ COREDESCRIPTOR ] + → Magic + → VM core file version + → VBox version + → Number of vCPUs etc. +[ Note Header, type NT_VBOXCPU ] - one for each vCPU +[ vCPU 1 Note Header ] + [ DBGFCORECPU - vCPU 1 dump ] +[ Additional Notes + Data ] - currently unused +[ Memory dump ]</screen> + + <para> + The memory descriptors contain physical addresses relative to + the guest and not virtual addresses. Regions of memory such as + MMIO regions are not included in the core file. + </para> + + <para> + The relevant data structures and definitions can be found in the + &product-name; sources under the following header files: + <filename>include/VBox/dbgfcorefmt.h</filename>, + <filename>include/iprt/x86.h</filename> and + <filename>src/VBox/Runtime/include/internal/ldrELFCommon.h</filename>. + </para> + + <para> + The VM core file can be inspected using + <command>elfdump</command> and GNU <command>readelf</command> or + other similar utilities. + </para> + + </sect2> + + </sect1> + + <sect1 id="ts_general"> + + <title>General Troubleshooting</title> + + <sect2 id="ts_config-periodic-flush"> + + <title>Guest Shows IDE/SATA Errors for File-Based Images on Slow Host File + System</title> + + <para> + Occasionally, some host file systems provide very poor writing + performance and as a consequence cause the guest to time out + IDE/SATA commands. This is normal behavior and should normally + cause no real problems, as the guest should repeat commands that + have timed out. However, guests such as some Linux versions have + severe problems if a write to an image file takes longer than + about 15 seconds. Some file systems however require more than a + minute to complete a single write, if the host cache contains a + large amount of data that needs to be written. + </para> + + <para> + The symptom for this problem is that the guest can no longer + access its files during large write or copying operations, + usually leading to an immediate hang of the guest. + </para> + + <para> + In order to work around this problem, the true fix is to use a + faster file system that does not exhibit such unacceptable write + performance, it is possible to flush the image file after a + certain amount of data has been written. This interval is + normally infinite, but can be configured individually for each + disk of a VM. + </para> + + <para> + For IDE disks use the following command: + </para> + +<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> +"VBoxInternal/Devices/piix3ide/0/LUN#[<replaceable>x</replaceable>]/Config/FlushInterval" [<replaceable>b</replaceable>]</screen> + + <para> + For SATA disks use the following command: + </para> + +<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> +"VBoxInternal/Devices/ahci/0/LUN#[<replaceable>x</replaceable>]/Config/FlushInterval" [<replaceable>b</replaceable>]</screen> + + <para> + <literal>[<replaceable>x</replaceable>]</literal> specifies the + disk. For IDE, <literal>0</literal> represents device 0 on the + primary channel, <literal>1</literal> represents device 1 on the + primary channel, <literal>2</literal> represents device 0 on the + secondary channel, and <literal>3</literal> represents device 1 + on the secondary channel. For SATA, use values between + <literal>0</literal> and <literal>29</literal>. This + configuration option applies to disks only. Do not use this + option for CD or DVD drives. + </para> + + <para> + The unit of the interval + (<literal>[<replaceable>b</replaceable>]</literal>) is the + number of bytes written since the last flush. The value for it + must be selected so that the occasional long write delays do not + occur. Since the proper flush interval depends on the + performance of the host and the host filesystem, finding the + optimal value that makes the problem disappear requires some + experimentation. Values between 1000000 and 10000000 (1 to 10 + megabytes) are a good starting point. Decreasing the interval + both decreases the probability of the problem and the write + performance of the guest. Setting the value unnecessarily low + will cost performance without providing any benefits. An + interval of 1 will cause a flush for each write operation and + should solve the problem in any case, but has a severe write + performance penalty. + </para> + + <para> + Providing a value of <literal>0</literal> for + <literal>[<replaceable>b</replaceable>]</literal> is treated as + an infinite flush interval, effectively disabling this + workaround. Removing the extra data key by specifying no value + for <literal>[<replaceable>b</replaceable>]</literal> has the + same effect. + </para> + + </sect2> + + <sect2 id="ts_ide-sata-flush"> + + <title>Responding to Guest IDE/SATA Flush Requests</title> + + <para> + If desired, the virtual disk images can be flushed when the + guest issues the IDE FLUSH CACHE command. Normally these + requests are ignored for improved performance. The parameters + below are only accepted for disk drives. They must not be set + for DVD drives. + </para> + + <para> + To enable flushing for IDE disks, issue the following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal/Devices/piix3ide/0/LUN#[<replaceable>x</replaceable>]/Config/IgnoreFlush" 0</screen> + + <para> + <literal>[<replaceable>x</replaceable>]</literal> specifies the + disk. Enter <literal>0</literal> for device 0 on the primary + channel, <literal>1</literal> for device 1 on the primary + channel, <literal>2</literal> for device 0 on the secondary + channel, or <literal>3</literal> for device 1 on the secondary + channel. + </para> + + <para> + To enable flushing for SATA disks, issue the following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal/Devices/ahci/0/LUN#[x]/Config/IgnoreFlush" 0</screen> + + <para> + The value [x] that selects the disk can be a value between 0 and + 29. + </para> + + <para> + Note that this does not affect the flushes performed according + to the configuration described in + <xref linkend="ts_config-periodic-flush"/>. Restoring the + default of ignoring flush commands is possible by setting the + value to 1 or by removing the key. + </para> + + </sect2> + + <sect2 id="ts_host-freq-boost"> + + <title>Performance Variation with Frequency Boosting</title> + + <para> + Many multicore processors support some form of frequency + boosting, which means that if only one core is utilized, it can + run possibly 50% faster or even more than the rated CPU + frequency. This causes measured performance to vary somewhat as + a function of the momentary overall system load. The exact + behavior depends strongly on the specific processor model. + </para> + + <para> + As a consequence, benchmarking on systems which utilize + frequency boosting may produce unstable and non-repeatable + results. This is especially true if benchmark runs are short, of + the order of seconds. To obtain stable results, benchmarks must + be run over longer periods of time and with a constant system + load apart from the VM being tested. + </para> + + </sect2> + + <sect2 id="ts_host-freq-scaling"> + + <title>Frequency Scaling Effect on CPU Usage</title> + + <para> + On some hardware platforms and operating systems, CPU frequency + scaling may cause CPU usage reporting to be highly misleading. + This happens in situations when the host CPU load is significant + but not heavy, such as between 15% to 30% of the maximum. + </para> + + <para> + Most operating systems determine CPU usage in terms of time + spent, measuring for example how many nanoseconds the systems or + a process was active within one second. However, in order to + save energy, systems can significantly scale down CPU speed when + the system is not fully loaded. When the CPU is running at for + example one half of its maximum speed, the same number of + instructions will take roughly twice as long to execute compared + to running at full speed. + </para> + + <para> + Depending on the specific hardware and host OS, this effect can + very significantly skew the CPU usage reported by the OS. The + reported CPU usage can be several times higher than what it + would have been had the CPU been running at full speed. The + effect can be observed both on the host OS and in a guest OS. + </para> + + </sect2> + + <sect2 id="ts_win-cpu-usage-rept"> + + <title>Inaccurate Windows CPU Usage Reporting</title> + + <para> + CPU usage reporting tools which come with Windows, such as Task + Manager or Resource Monitor, do not take the time spent + processing hardware interrupts into account. If the interrupt + load is heavy, with thousands of interrupts per second, CPU + usage may be significantly underreported. + </para> + + <para> + This problem affects Windows as both host and guest OS. + Sysinternals tools, such as Process Explorer, do not suffer from + this problem. + </para> + + </sect2> + + <sect2 id="ts_host-powermgmt"> + + <title>Poor Performance Caused by Host Power Management</title> + + <para> + On some hardware platforms and operating systems, virtualization + performance is negatively affected by host CPU power management. + The symptoms may be choppy audio in the guest or erratic guest + clock behavior. + </para> + + <para> + Some of the problems may be caused by firmware and/or host + operating system bugs. Therefore, updating the firmware and + applying operating systems fixes is recommended. + </para> + + <para> + For optimal virtualization performance, the C1E power state + support in the system's BIOS should be disabled, if such a + setting is available. Not all systems support the C1E power + state. On Intel systems, the <literal>Intel C State</literal> + setting should be disabled. Disabling other power management + settings may also improve performance. However, a balance + between performance and power consumption must always be + considered. + </para> + + </sect2> + + <sect2 id="ts_gui-2d-grayed-out"> + + <title>GUI: 2D Video Acceleration Option is Grayed Out</title> + + <para> + To use 2D Video Acceleration within &product-name;, your host's + video card should support certain OpenGL extensions. On startup, + &product-name; checks for those extensions, and, if the test + fails, this option is silently grayed out. + </para> + + <para> + To find out why it has failed, you can manually execute the + following command: + </para> + +<screen>$ VBoxTestOGL --log "log_file_name" --test 2D</screen> + + <para> + It will list the required OpenGL extensions one by one and will + show you which one failed the test. This usually means that you + are running an outdated or misconfigured OpenGL driver on your + host. It can also mean that your video chip is lacking required + functionality. + </para> + + </sect2> + + </sect1> + + <sect1 id="ts_win-guests"> + + <title>Windows Guests</title> + + <sect2 id="ts_win7-guest-usb3-support"> + + <title>No USB 3.0 Support in Windows 7 Guests</title> + + <para> + If a Windows 7 or Windows Server 2008 R2 guest is configured for + USB 3.0 (xHCI) support, the guest OS will not have any USB + support at all. This happens because Windows 7 predates USB 3.0 + and therefore does not ship with any xHCI drivers. Microsoft + also does not offer any vendor-provided xHCI drivers through + Windows Update. + </para> + + <para> + To solve this problem, it is necessary to download and install + the Intel xHCI driver in the guest. Intel offers the driver as + the USB 3.0 eXtensible Host Controller (xHCI) driver for Intel 7 + Series/C216 chipsets. + </para> + + <para> + Note that the driver only supports Windows 7 and Windows Server + 2008 R2. The driver package includes support for both 32-bit and + 64-bit OS variants. + </para> + + </sect2> + + <sect2 id="ts_win-guest-bluescreen"> + + <title>Windows Bluescreens After Changing VM Configuration</title> + + <para> + Changing certain virtual machine settings can cause Windows + guests to fail during start up with a bluescreen. This may + happen if you change VM settings after installing Windows, or if + you copy a disk image with an already installed Windows to a + newly created VM which has settings that differ from the + original machine. + </para> + + <para> + This applies in particular to the following settings: + </para> + + <itemizedlist> + + <listitem> + <para> + The ACPI and I/O APIC settings should never be changed after + installing Windows. Depending on the presence of these + hardware features, the Windows installation program chooses + special kernel and device driver versions and will fail to + startup should these hardware features be removed. Enabling + them for a Windows VM which was installed without them does + not cause any harm. However, Windows will not use these + features in this case. + </para> + </listitem> + + <listitem> + <para> + Changing the storage controller hardware will cause bootup + failures as well. This might also apply to you if you copy a + disk image from an older version of &product-name; to a new + virtual machine. The default subtype of IDE controller + hardware used by &product-name; is PIIX4. Make sure that the + storage controller settings are identical. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="ts_win-guest-bluescreen-smp"> + + <title>Windows 0x101 Bluescreens with SMP Enabled (IPI Timeout)</title> + + <para> + If a VM is configured to have more than one processor + (symmetrical multiprocessing, SMP), some configurations of + Windows guests crash with an 0x101 error message, indicating a + timeout for interprocessor interrupts (IPIs). These interrupts + synchronize memory management between processors. + </para> + + <para> + According to Microsoft, this is due to a race condition in + Windows. A hotfix is available from Microsoft. + </para> + + <para> + If this does not help, please reduce the number of virtual + processors to 1. + </para> + + </sect2> + + <sect2 id="ts_win2k-guest-install"> + + <title>Windows 2000 Installation Failures</title> + + <para> + When installing Windows 2000 guests, you might run into one of + the following issues: + </para> + + <itemizedlist> + + <listitem> + <para> + Installation reboots, usually during component registration. + </para> + </listitem> + + <listitem> + <para> + Installation fills the whole hard disk with empty log files. + </para> + </listitem> + + <listitem> + <para> + Installation complains about a failure installing + <filename>msgina.dll</filename>. + </para> + </listitem> + + </itemizedlist> + + <para> + These problems are all caused by a bug in the hard disk driver + of Windows 2000. After issuing a hard disk request, there is a + race condition in the Windows driver code which leads to + corruption if the operation completes too fast. For example, the + hardware interrupt from the IDE controller arrives too soon. + With physical hardware, there is a guaranteed delay in most + systems so the problem is usually hidden there. However, it + should be possible to also reproduce it on physical hardware. In + a virtual environment, it is possible for the operation to be + done immediately, especially on very fast systems with multiple + CPUs, and the interrupt is signaled sooner than on a physical + system. The solution is to introduce an artificial delay before + delivering such interrupts. This delay can be configured for a + VM using the following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal/Devices/piix3ide/0/Config/IRQDelay" 1</screen> + + <para> + This sets the delay to one millisecond. In case this does not + help, increase it to a value between 1 and 5 milliseconds. + Please note that this slows down disk performance. After + installation, you should be able to remove the key, or set it to + 0. + </para> + + </sect2> + + <sect2 id="ts_win-guest-bluescreen-record-info"> + + <title>How to Record Bluescreen Information from Windows Guests</title> + + <para> + When Windows guests run into a kernel crash, they display a + bluescreen error. Depending on how Windows is configured, the + information will remain on the screen until the machine is + restarted or it will reboot automatically. During installation, + Windows is usually configured to reboot automatically. With + automatic reboots, there is no chance to record the bluescreen + information which might be important for problem determination. + </para> + + <para> + &product-name; provides a method of halting a guest when it + wants to perform a reset. In order to enable this feature, use + the following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal/PDM/HaltOnReset" 1</screen> + + </sect2> + + <sect2 id="ts_win-vista-guest-networking"> + + <title>No Networking in Windows Vista Guests</title> + + <para> + With Windows Vista, Microsoft dropped support for the AMD PCNet + card that legacy versions of &product-name; used to provide as + the default virtual network card. For Windows Vista guests, + &product-name; now uses an Intel E1000 card by default. + </para> + + <para> + If, for some reason, you still want to use the AMD card, you + need to download the PCNet driver from the AMD website. This + driver is available for 32-bit Windows only. You can transfer it + into the virtual machine using a shared folder. See + <xref linkend="sharedfolders" />. + </para> + + </sect2> + + <sect2 id="ts_win-guest-high-cpu"> + + <title>Windows Guests may Cause a High CPU Load</title> + + <para> + Several background applications of Windows guests, especially + virus scanners, are known to increase the CPU load notably even + if the guest appears to be idle. We recommend to deactivate + virus scanners within virtualized guests if possible. + </para> + + </sect2> + + <sect2 id="ts_win-guest-shared-folders-access-delay"> + + <title>Long Delays When Accessing Shared Folders</title> + + <para> + The performance for accesses to shared folders from a Windows + guest might be decreased due to delays during the resolution of + the &product-name; shared folders name service. To fix these + delays, add the following entries to the file + <filename>\windows\system32\drivers\etc\lmhosts</filename> of + the Windows guest: + </para> + +<screen>255.255.255.255 VBOXSVR #PRE +255.255.255.255 VBOXSRV #PRE</screen> + + <para> + After doing this change, a reboot of the guest is required. + </para> + + </sect2> + + <sect2 id="ts_win98-guest-usb-tablet-coordinates"> + + <title>USB Tablet Coordinates Wrong in Windows 98 Guests</title> + + <para> + If a Windows 98 VM is configured to use the emulated USB tablet + (absolute pointing device), the coordinate translation may be + incorrect and the pointer is restricted to the upper left + quarter of the guest's screen. + </para> + + <para> + The USB HID (Human Interface Device) drivers in Windows 98 are + very old and do not handle tablets in the same way as modern + operating systems do. To work around the problem, use the + following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal/USB/HidMouse/0/Config/CoordShift" 0</screen> + + <para> + To restore the default behavior, remove the key or set its value + to 1. + </para> + + </sect2> + + <sect2 id="ts_win-guest-active-dir-domain"> + + <title>Windows Guests are Removed From an Active Directory Domain After + Restoring a Snapshot</title> + + <para> + If a Windows guest is a member of an Active Directory domain and + the snapshot feature of &product-name; is used, it could be + removed from the Active Direcory domain after you restore an + older snapshot. + </para> + + <para> + This is caused by automatic machine password changes performed + by Windows at regular intervals for security purposes. You can + disable this feature as shown in the following article from + Microsoft: + <ulink url="http://support.microsoft.com/kb/154501" />. + </para> + + </sect2> + + <sect2 id="ts_win31-ram-limitations"> + + <title>Windows 3.x Limited to 64 MB RAM</title> + + <para> + Windows 3.x guests are typically limited to 64 MB RAM, even if a + VM is assigned much more memory. While Windows 3.1 is + theoretically capable of using up to 512 MB RAM, it only uses + memory available through the XMS interface. Versions of + HIMEM.SYS, the Microsoft XMS manager, shipped with MS-DOS and + Microsoft Windows 3.x can only use up to 64 MB on standard PCs. + </para> + + <para> + This is a known HIMEM.SYS limitation. Windows 3.1 memory limits + are described in detail in Microsoft Knowledge base article KB + 84388. + </para> + + <para> + It is possible for Windows 3.x guests to utilize more than 64 MB + RAM if a different XMS provider is used. That could be a newer + HIMEM.SYS version, such as that shipped with Windows 98, or a + more capable third-party memory manager, such as QEMM. + </para> + + </sect2> + + </sect1> + + <sect1 id="ts_lin-x11-guests"> + + <title>Linux and X11 Guests</title> + + <sect2 id="ts_linux-guest-high-cpu"> + + <title>Linux Guests May Cause a High CPU load</title> + + <para> + Some Linux guests may cause a high CPU load even if the guest + system appears to be idle. This can be caused by a high timer + frequency of the guest kernel. Some Linux distributions, for + example Fedora, ship a Linux kernel configured for a timer + frequency of 1000Hz. We recommend to recompile the guest kernel + and to select a timer frequency of 100Hz. + </para> + + <para> + Linux kernels shipped with Red Hat Enterprise Linux, as well as + kernels of related Linux distributions, such as CentOS and + Oracle Linux, support a kernel parameter + <emphasis>divider=N</emphasis>. Hence, such kernels support a + lower timer frequency without recompilation. We suggest you add + the kernel parameter <emphasis>divider=10</emphasis> to select a + guest kernel timer frequency of 100Hz. + </para> + + </sect2> + + <sect2 id="ts_linux-buggy"> + + <title>Buggy Linux 2.6 Kernel Versions</title> + + <para> + The following bugs in Linux kernels prevent them from executing + correctly in &product-name;, causing VM boot crashes: + </para> + + <itemizedlist> + + <listitem> + <para> + The Linux kernel version 2.6.18, and some 2.6.17 versions, + introduced a race condition that can cause boot crashes in + &product-name;. Please use a kernel version 2.6.19 or later. + </para> + </listitem> + + <listitem> + <para> + With hardware virtualization and the I/O APIC enabled, + kernels before 2.6.24-rc6 may panic on boot with the + following message: + </para> + +<screen>Kernel panic - not syncing: IO-APIC + timer doesn't work! Boot with +apic=debug and send a report. Then try booting with the 'noapic' option</screen> + + <para> + If you see this message, either disable hardware + virtualization or the I/O APIC as described in + <xref linkend="settings-system" />, or upgrade the guest to + a newer kernel. + </para> + + <para> + See + <ulink url="http://www.mail-archive.com/git-commits-head@vger.kernel.org/msg30813.html" /> + for details about the kernel fix. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="ts_linux-guest-x11-services"> + + <title>Shared Clipboard, Auto-Resizing, and Seamless Desktop in X11 Guests</title> + + <para> + Guest desktop services in guests running the X11 window system + such as Oracle Solaris and Linux, are provided by a guest + service called <command>VBoxClient</command>, which runs under + the ID of the user who started the desktop session and is + automatically started using the following command lines when + your X11 user session is started if you are using a common + desktop environment such as Gnome or KDE. + </para> + +<screen>$ VBoxClient --clipboard +$ VBoxClient --display +$ VBoxClient --seamless</screen> + + <para> + If a particular desktop service is not working correctly, it is + worth checking whether the process which should provide it is + running. + </para> + + <para> + The <command>VBoxClient</command> processes create files in the + user's home directory with names of the form + <filename>.vboxclient-*.pid</filename> when they are running in + order to prevent a given service from being started twice. It + can happen due to misconfiguration that these files are created + owned by root and not deleted when the services are stopped, + which will prevent them from being started in future sessions. + If the services cannot be started, you may wish to check whether + these files still exist. + </para> + + </sect2> + + </sect1> + + <sect1 id="ts_sol-guests"> + + <title>Oracle Solaris Guests</title> + + <sect2 id="ts_solaris-10-guest-slow-boot-smp"> + + <title>Certain Oracle Solaris 10 Releases May Take a Long Time to Boot with SMP</title> + + <para> + When using more than one CPU, Oracle Solaris 10 10/08, and + Oracle Solaris 10 5/09 may take a long time to boot and may + print warnings on the system console regarding failures to read + from disk. This is a bug in Oracle Solaris 10 which affects + specific physical and virtual configurations. It is caused by + trying to read microcode updates from the boot disk when the + disk interrupt is reassigned to a not yet fully initialized + secondary CPU. Disk reads will time out and fail, triggering + delays of about 45 seconds and warnings. + </para> + + <para> + The recommended solution is upgrading to at least Oracle Solaris + 10 10/09 which includes a fix for this problem. Alternative + solutions include restricting the number of virtual CPUs to one + or possibly using a different storage controller. + </para> + + </sect2> + + <sect2 id="ts_solaris-no-e1000-bm"> + + <title>Older Solaris Releases Do Not Work with E1000 Ethernet</title> + + <para> + Solaris releases before Solaris 10 1/06, including Solaris 9, Solaris + 10 1/05 (GA), and Solaris 10 3/05 (HW2), are unable to communicate + through the Intel E1000 card. The Solaris e1000g driver does not enable + PCI bus mastering for the network adapter and is therefore unable to send + and receive data. This problem appears to be specific to the e1000g + driver and does not reflect general Solaris driver behavior. + </para> + + <para> + The AMD PCnet emulation (using the Solaris pcn driver) can be used + instead of Intel E1000. Solaris 10 1/06 (U1) and later releases do not + have this problem and work with the emulated E1000 ethernet + controller. + </para> + + </sect2> + + </sect1> + + <sect1 id="ts_win-hosts"> + + <title>Windows Hosts</title> + + <sect2 id="ts_win-dnd-uipi"> + + <title>Drag'n Drop not Working</title> + + <para> + Microsoft Windows uses technologies like UAC (User Account Control) and + UIPI (User Interface Privilege Isolation) to prevent and/or mitigate + security issues. By default, UAC and UIPI are enabled. + </para> + <para> + When a &product-name; VM process is running with a higher so-called + privilege level than another process that wants to interact with the + VM process via drag'n drop (or system clipboard), Windows prevents this + by default due to security reasons. This results in &product-name; not + being able to receive any Windows messages for drag'n drop. + + To make this work, the &product-name; VM process must be running with + the same (or lower) privilege level as the process its interacting with + using drag'n drop. + + Disabling UAC and/or UIPI is not recommended. + </para> + + </sect2> + + <sect2 id="ts_win-host-com-server"> + + <title>VBoxSVC Out-of-Process COM Server Issues</title> + + <para> + &product-name; makes use of the Microsoft Component Object Model + (COM) for interprocess and intraprocess communication. This + enables &product-name; to share a common configuration among + different virtual machine processes and provide several user + interface options based on a common architecture. All global + status information and configuration is maintained by the + process <filename>VBoxSVC.exe</filename>, which is an + out-of-process COM server. Whenever an &product-name; process is + started, it requests access to the COM server and Windows + automatically starts the process. Note that it should never be + started by the end user. + </para> + + <para> + When the last process disconnects from the COM server, it will + terminate itself after some seconds. The &product-name; + configuration XML files are maintained and owned by the COM + server and the files are locked whenever the server runs. + </para> + + <para> + In some cases, such as when a virtual machine is terminated + unexpectedly, the COM server will not notice that the client is + disconnected and stay active for a longer period of 10 minutes + or so, keeping the configuration files locked. In other rare + cases the COM server might experience an internal error and + subsequently other processes fail to initialize it. In these + situations, it is recommended to use the Windows task manager to + kill the process <filename>VBoxSVC.exe</filename>. + </para> + + </sect2> + + <sect2 id="ts_win-host-cd-dvd-changes"> + + <title>CD and DVD Changes Not Recognized</title> + + <para> + In case you have assigned a physical CD or DVD drive to a guest + and the guest does not notice when the medium changes, make sure + that the Windows media change notification (MCN) feature is not + turned off. This is represented by the following key in the + Windows registry: + </para> + +<screen>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Cdrom\Autorun</screen> + + <para> + Certain applications may disable this key against Microsoft's + advice. If it is set to 0, change it to 1 and reboot your + system. &product-name; relies on Windows notifying it of media + changes. + </para> + + </sect2> + + <sect2 id="ts_win-host-rdp-client"> + + <title>Sluggish Response When Using Microsoft RDP Client</title> + + <para> + If connecting to a Virtual Machine using the Microsoft RDP + client, called a Remote Desktop Connection, there can be large + delays between input such as moving the mouse over a menu and + output. This is because this RDP client collects input for a + certain time before sending it to the RDP server. + </para> + + <para> + The interval can be decreased by setting a Windows registry key + to smaller values than the default of 100. The key does not + exist initially and must be of type DWORD. The unit for its + values is milliseconds. Values around 20 are suitable for + low-bandwidth connections between the RDP client and server. + Values around 4 can be used for a gigabit Ethernet connection. + Generally values below 10 achieve a performance that is very + close to that of the local input devices and screen of the host + on which the Virtual Machine is running. + </para> + + <para> + Depending whether the setting should be changed for an + individual user or for the system, set either of the following. + </para> + +<screen>HKEY_CURRENT_USER\Software\Microsoft\Terminal Server Client\Min Send Interval</screen> + +<screen>HKEY_LOCAL_MACHINE\Software\Microsoft\Terminal Server Client\Min Send Interval</screen> + + </sect2> + + <sect2 id="ts_win-host-iscsi"> + + <title>Running an iSCSI Initiator and Target on a Single System</title> + + <para> + Deadlocks can occur on a Windows host when attempting to access + an iSCSI target running in a guest virtual machine with an iSCSI + initiator, such as a Microsoft iSCSI Initiator, that is running + on the host. This is caused by a flaw in the Windows cache + manager component, and causes sluggish host system response for + several minutes, followed by a "Delayed Write Failed" error + message in the system tray or in a separate message window. The + guest is blocked during that period and may show error messages + or become unstable. + </para> + + <para> + Setting the <literal>VBOX_DISABLE_HOST_DISK_CACHE</literal> + environment variable to <literal>1</literal> enables a + workaround for this problem until Microsoft addresses the issue. + For example, open a command prompt window and start + &product-name; like this: + </para> + +<screen>set VBOX_DISABLE_HOST_DISK_CACHE=1 +VirtualBox</screen> + + <para> + While this will decrease guest disk performance, especially + writes, it does not affect the performance of other applications + running on the host. + </para> + + </sect2> + + <sect2 id="ts_win-host-bridged-network-adapters"> + + <title>Bridged Networking Adapters Missing</title> + + <para> + If no bridged adapters show up in the + <emphasis role="bold">Networking</emphasis> section of the VM + settings, this typically means that the bridged networking + driver was not installed properly on your host. This could be + due to the following reasons: + </para> + + <itemizedlist> + + <listitem> + <para> + The maximum allowed filter count was reached on the host. In + this case, the MSI log would mention the + <literal>0x8004a029</literal> error code returned on NetFlt + network component install, as follows: + </para> + +<screen>VBoxNetCfgWinInstallComponent: Install failed, hr (0x8004a029)</screen> + + <para> + You can try to increase the maximum filter count in the + Windows registry using the following key: + </para> + +<screen>HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Network\MaxNumFilters</screen> + + <para> + The maximum number allowed is 14. After a reboot, try to + reinstall &product-name;. + </para> + </listitem> + + <listitem> + <para> + The INF cache is corrupt. In this case, the install log at + <filename>%windir%\inf\setupapi.dev.log</filename> would + typically mention the failure to find a suitable driver + package for either the <command>sun_VBoxNetFlt</command> or + <command>sun_VBoxNetFltmp</command> components. The solution + then is to uninstall &product-name;, remove the INF cache + (<filename>%windir%\inf\INFCACHE.1</filename>), reboot and + try to reinstall &product-name;. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="ts_win-host-host-only-network-adapters"> + + <title>Host-Only Networking Adapters Cannot be Created</title> + + <para> + If a host-only adapter cannot be created, either with the + &vbox-mgr; or the <command>VBoxManage</command> command, then + the INF cache is probably corrupt. In this case, the install log + at <filename>%windir%\inf\setupapi.dev.log</filename> would + typically mention the failure to find a suitable driver package + for the <filename>sun_VBoxNetAdp</filename> component. Again, as + with the bridged networking problem described above, the + solution is to uninstall &product-name;, remove the INF cache + (<filename>%windir%\inf\INFCACHE.1</filename>), reboot and try + to reinstall &product-name;. + </para> + + </sect2> + + </sect1> + + <sect1 id="ts_lin-hosts"> + + <title>Linux Hosts</title> + + <sect2 id="ts_linux-kernelmodule-fails-to-load"> + + <title>Linux Kernel Module Refuses to Load</title> + + <para> + If the &product-name; kernel module, <command>vboxdrv</command>, + refuses to load you may see an <literal>Error inserting vboxdrv: + Invalid argument</literal> message. As root, check the output of + the <command>dmesg</command> command to find out why the load + failed. Most probably the kernel disagrees with the version of + <command>gcc</command> used to compile the module. Make sure + that you use the same compiler that was used to build the + kernel. + </para> + + </sect2> + + <sect2 id="ts_linux-host-cd-dvd-not-found"> + + <title>Linux Host CD/DVD or Floppy Disk Drive Not Found</title> + + <para> + If you have configured a virtual machine to use the host's CD or + DVD drive or floppy disk drive, but this does not appear to + work, make sure that the current user has permission to access + the corresponding Linux device file. For example, for a CD or + DVD drive this may be <filename>/dev/hdc</filename>, + <filename>/dev/scd0</filename>, <filename>/dev/cdrom</filename> + or similar. On most distributions, the user must be added to a + corresponding group, usually called <command>cdrom</command> or + <command>cdrw</command> or <command>floppy</command>. + </para> + + <para> + On supported Linux distributions, &product-name; uses + <command>udev</command> to locate hardware such as CD/DVD drives + and floppy disk drives. + </para> + + </sect2> + + <sect2 id="ts_linux-host-ide-messages"> + + <title>Strange Guest IDE Error Messages When Writing to CD or DVD</title> + + <para> + If the experimental CD or DVD writer support is enabled with an + incorrect host or guest configuration, it is possible that any + attempt to access the CD or DVD writer fails and simply results + in guest kernel error messages for Linux guests or application + error messages for Windows guests. &product-name; performs the + usual consistency checks when a VM is powered up. In particular, + it aborts with an error message if the device for the CD or DVD + writer is not writable by the user starting the VM. But + &product-name; cannot detect all misconfigurations. The + necessary host and guest OS configuration is not specific for + &product-name;, but a few frequent problems are listed here + which occurred in connection with &product-name;. + </para> + + <para> + Special care must be taken to use the correct device. The + configured host CD or DVD device file name, in most cases + <filename>/dev/cdrom</filename>, must point to the device that + allows writing to the CD or DVD unit. For CD or DVD writer units + connected to a SCSI controller or to a IDE controller that + interfaces to the Linux SCSI subsystem, common for some SATA + controllers, this must refer to the SCSI device node, such as + <filename>/dev/scd0</filename>. Even for IDE CD or DVD writer + units this must refer to the appropriate SCSI CD-ROM device + node, such as <filename>/dev/scd0</filename>, if the + <command>ide-scsi</command> kernel module is loaded. This module + is required for CD or DVD writer support with some early 2.6 + kernels. Many Linux distributions load this module whenever a CD + or DVD writer is detected in the system, even if the kernel + would support CD or DVD writers without the module. + &product-name; supports the use of IDE device files, such as + <filename>/dev/hdc</filename>, provided the kernel supports this + and the <command>ide-scsi</command> module is not loaded. + </para> + + <para> + Similar rules, except that within the guest the CD or DVD writer + is always an IDE device, apply to the guest configuration. Since + this setup is very common, it is likely that the default + configuration of the guest works as expected. + </para> + + </sect2> + + <sect2 id="ts_linux-host-vboxsvc"> + + <title>VBoxSVC IPC Issues</title> + + <para> + On Linux, &product-name; makes use of a custom version of + Mozilla XPCOM (cross platform component object model) for + interprocess and intraprocess communication (IPC). The process + <command>VBoxSVC</command> serves as a communication hub between + different &product-name; processes and maintains the global + configuration, such as the XML database. When starting an + &product-name; component, the processes + <command>VBoxSVC</command> and <command>VBoxXPCOMIPCD</command> + are started automatically. They are only accessible from the + user account they are running under. <command>VBoxSVC</command> + owns the &product-name; configuration database which normally + resides in <filename>~/.config/VirtualBox</filename>, or the + appropriate configuration directory for your operating system. + While it is running, the configuration files are locked. + Communication between the various &product-name; components and + <command>VBoxSVC</command> is performed through a local domain + socket residing in + <filename>/tmp/.vbox-<replaceable>username</replaceable>-ipc</filename>. + In case there are communication problems, such as an + &product-name; application cannot communicate with + <command>VBoxSVC</command>, terminate the daemons and remove the + local domain socket directory. + </para> + + </sect2> + + <sect2 id="ts_usb-linux"> + + <title>USB Not Working</title> + + <para> + If USB is not working on your Linux host, make sure that the + current user is a member of the <literal>vboxusers</literal> + group. Please keep in mind that group membership does not take + effect immediately but rather at the next login. If available, + the <command>newgrp</command> command may avoid the need for a + logout and login. + </para> + + </sect2> + + <sect2 id="ts_linux-host-grsec"> + + <title>PAX/grsec Kernels</title> + + <para> + Linux kernels including the grsec patch, see + <ulink url="http://www.grsecurity.net/" />, and derivates have + to disable PAX_MPROTECT for the <command>VBox</command> binaries + to be able to start a VM. The reason is that &product-name; has + to create executable code on anonymous memory. + </para> + + </sect2> + + <sect2 id="ts_linux-host-malloc"> + + <title>Linux Kernel vmalloc Pool Exhausted</title> + + <para> + When running a large number of VMs with a lot of RAM on a Linux + system, say 20 VMs with 1 GB of RAM each, additional VMs might + fail to start with a kernel error saying that the vmalloc pool + is exhausted and should be extended. The error message also + tells you to specify <literal>vmalloc=256MB</literal> in your + kernel parameter list. If adding this parameter to your GRUB or + LILO configuration makes the kernel fail to boot, with an error + message such as <literal>failed to mount the root + partition</literal>, then you have probably run into a memory + conflict of your kernel and initial RAM disk. This can be solved + by adding the following parameter to your GRUB configuration: + </para> + +<screen>uppermem 524288</screen> + + </sect2> + + </sect1> + + <sect1 id="ts_sol-hosts"> + + <title>Oracle Solaris Hosts</title> + + <sect2 id="ts_sol-host-zfs"> + + <title>Cannot Start VM, Not Enough Contiguous Memory</title> + + <para> + The ZFS file system is known to use nearly all available RAM as + cache if the default system settings are not changed. This may + lead to a heavy fragmentation of the host memory preventing + &product-name; VMs from being started. We recommend to limit the + ZFS cache by adding the following line to + <filename>/etc/system</filename>, where + <replaceable>xxxx</replaceable> bytes is the amount of memory + usable for the ZFS cache. + </para> + +<screen>set zfs:zfs_arc_max = xxxx</screen> + + </sect2> + + </sect1> + +</chapter> diff --git a/doc/manual/en_US/user_VBoxManage.xml b/doc/manual/en_US/user_VBoxManage.xml new file mode 100644 index 00000000..4358ba62 --- /dev/null +++ b/doc/manual/en_US/user_VBoxManage.xml @@ -0,0 +1,521 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + user_VBoxManage.xml: + VBoxManage documentation for the user manual. + + This XML document is also be used for generating the help text + built into VBoxManage as well as manpages (hacking in progress). +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="vboxmanage"> + + <title>VBoxManage</title> + + <sect1 id="vboxmanage-intro"> + + <title>Introduction</title> + + <para> + As briefly mentioned in <xref linkend="frontends" />, + <command>VBoxManage</command> is the command-line interface to + &product-name;. With it, you can completely control &product-name; + from the command line of your host operating system. + <command>VBoxManage</command> supports all the features that the + graphical user interface gives you access to, but it supports a + lot more than that. It exposes all the features of the + virtualization engine, even those that cannot be accessed from the + GUI. + </para> + + <para> + You will need to use the command line if you want to do the + following: + </para> + + <itemizedlist> + + <listitem> + <para> + Use a different user interface than the main GUI such as the + VBoxHeadless server. + </para> + </listitem> + + <listitem> + <para> + Control some of the more advanced and experimental + configuration settings for a VM. + </para> + </listitem> + + </itemizedlist> + + <para> + There are two main things to keep in mind when using + <command>VBoxManage</command>. First, + <command>VBoxManage</command> must always be used with a specific + subcommand, such as <command>list</command> or + <command>createvm</command> or <command>startvm</command>. All the + subcommands that <command>VBoxManage</command> supports are + described in detail in <xref linkend="vboxmanage" />. + </para> + + <para> + Second, most of these subcommands require that you specify a + particular virtual machine after the subcommand. There are two + ways you can do this: + </para> + + <itemizedlist> + + <listitem> + <para> + You can specify the VM name, as it is shown in the + &product-name; GUI. Note that if that name contains spaces, + then you must enclose the entire name in double quotes. This + is always required with command line arguments that contain + spaces. For example: + </para> + +<screen>VBoxManage startvm "Windows XP"</screen> + </listitem> + + <listitem> + <para> + You can specify the UUID, which is the internal unique + identifier that &product-name; uses to refer to the virtual + machine. Assuming that the VM called "Windows XP" has the UUID + shown below, the following command has the same effect as the + previous example: + </para> + +<screen>VBoxManage startvm 670e746d-abea-4ba6-ad02-2a3b043810a5</screen> + </listitem> + + </itemizedlist> + + <para> + You can enter <command>VBoxManage list vms</command> to have all + currently registered VMs listed with all their settings, including + their respective names and UUIDs. + </para> + + <para> + Some typical examples of how to control &product-name; from the + command line are listed below: + </para> + + <itemizedlist> + + <listitem> + <para> + To create a new virtual machine from the command line and + immediately register it with &product-name;, use + <command>VBoxManage createvm</command> with the + <option>--register</option> option, as follows: + </para> + +<screen>$ VBoxManage createvm --name "SUSE 10.2" --register +VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable> +Copyright (C) 2005-2023 Oracle and/or its affiliates + +Virtual machine 'SUSE 10.2' is created. +UUID: c89fc351-8ec6-4f02-a048-57f4d25288e5 +Settings file: '/home/username/.config/VirtualBox/Machines/SUSE 10.2/SUSE 10.2.xml'</screen> + + <para> + As can be seen from the above output, a new virtual machine + has been created with a new UUID and a new XML settings file. + </para> + + <para> + For more details, see + <xref + linkend="vboxmanage-createvm" />. + </para> + </listitem> + + <listitem> + <para> + To show the configuration of a particular VM, use + <command>VBoxManage showvminfo</command>. See + <xref + linkend="vboxmanage-showvminfo" /> for details + and an example. + </para> + </listitem> + + <listitem> + <para> + To change settings while a VM is powered off, use + <command>VBoxManage modifyvm</command>. For example: + </para> + +<screen>VBoxManage modifyvm "Windows XP" --memory 512</screen> + + <para> + See also <xref linkend="vboxmanage-modifyvm" />. + </para> + </listitem> + + <listitem> + <para> + To change the storage configuration, such as to add a storage + controller and then a virtual disk, use <command>VBoxManage + storagectl</command> and <command>VBoxManage + storageattach</command>. See + <xref + linkend="vboxmanage-storagectl" /> and + <xref + linkend="vboxmanage-storageattach" />. + </para> + </listitem> + + <listitem> + <para> + To control VM operation, use one of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + To start a VM that is currently powered off, use + <command>VBoxManage startvm</command>. See + <xref + linkend="vboxmanage-startvm" />. + </para> + </listitem> + + <listitem> + <para> + To pause or save a VM that is currently running or change + some of its settings, use <command>VBoxManage + controlvm</command>. See + <xref + linkend="vboxmanage-controlvm" />. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="vboxmanage-cmd-overview"> + + <title>Commands Overview</title> + + <para> + When running <command>VBoxManage</command> without parameters or + when supplying an invalid command line, the following command + syntax list is shown. Note that the output will be slightly + different depending on the host platform. If in doubt, check the + output of <command>VBoxManage</command> for the commands available + on your particular host. + </para> + + <xi:include href="overview_man_VBoxManage-common.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-list.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-showvminfo.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-registervm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-unregistervm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-createvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-modifyvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-clonevm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-movevm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-encryptvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-cloud.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-cloudprofile.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-import.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-export.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-signova.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-startvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-controlvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-unattended.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-discardstate.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-adoptstate.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-snapshot.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-closemedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-storageattach.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-storagectl.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-bandwidthctl.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-showmediuminfo.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-createmedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-modifymedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-clonemedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-mediumproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-encryptmedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-checkmediumpwd.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-convertfromraw.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-mediumio.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-setextradata.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-getextradata.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-setproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-usbfilter.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-sharedfolder.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-guestproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-guestcontrol.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-debugvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-metrics.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-natnetwork.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-hostonlyif.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-hostonlynet.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-dhcpserver.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-usbdevsource.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-extpack.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-updatecheck.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-modifynvram.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <para> + Each time <command>VBoxManage</command> is invoked, only one + command can be executed. However, a command might support several + subcommands which then can be invoked in one single call. The + following sections provide detailed reference information on the + different commands. + </para> + + </sect1> + + <!-- TODO: Figure out how we can generate a file with the includes... The trouble is + that xpointer doesn't seem to allow including multiple elements. + + In the mean time, when adding new VBoxManage man pages to Config.kmk, + don't forget to add it here too. + --> + + <sect1 id="vboxmanage-general"> + + <title>General Options</title> + + <itemizedlist> + + <listitem> + <para> + <option>-v|--version</option>: Show the version of this tool + and exit. + </para> + </listitem> + + <listitem> + <para> + <option>--nologo</option>: Suppress the output of the logo + information. This option is useful for scripts. + </para> + </listitem> + + <listitem> + <para> + <option>--settingspw</option>: Specifiy a settings password. + </para> + </listitem> + + <listitem> + <para> + <option>--settingspwfile</option>: Specify a file containing + the settings password. + </para> + </listitem> + + </itemizedlist> + + <para> + The settings password is used for certain settings which need to + be stored in encrypted form for security reasons. At the moment, + the only encrypted setting is the iSCSI initiator secret, see + <xref linkend="vboxmanage-storageattach" />. As long as no + settings password is specified, this information is stored in + <emphasis>plain text</emphasis>. After using the + <option>--settingspw|--settingspwfile</option> option once, it + must be always used. Otherwise, the encrypted setting cannot be + unencrypted. + </para> + + </sect1> + + <!-- TODO: Check the overview/common man page --> + <xi:include href="user_man_VBoxManage-common.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-list.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-showvminfo.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-registervm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-unregistervm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-createvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-modifyvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-clonevm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-movevm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-encryptvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-cloud.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-cloudprofile.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-import.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-export.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-signova.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-startvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-controlvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-unattended.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-discardstate.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-adoptstate.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-snapshot.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-closemedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-storageattach.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-storagectl.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-bandwidthctl.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-showmediuminfo.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-createmedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-modifymedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-clonemedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-mediumproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-encryptmedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-checkmediumpwd.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-convertfromraw.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-mediumio.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-setextradata.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-getextradata.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-setproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-usbfilter.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-sharedfolder.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-guestproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-guestcontrol.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-debugvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-metrics.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-natnetwork.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-hostonlyif.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-hostonlynet.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-dhcpserver.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-usbdevsource.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-extpack.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-updatecheck.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-modifynvram.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <!-- TODO: Figure out how we can handle other manpages. The xml is bolted to + sect1, so it's not possible to have them "in place" --> + + <xi:include href="user_man_vboximg-mount.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + +</chapter> diff --git a/doc/manual/en_US/user_VirtualBoxAPI.xml b/doc/manual/en_US/user_VirtualBoxAPI.xml new file mode 100644 index 00000000..67eebb30 --- /dev/null +++ b/doc/manual/en_US/user_VirtualBoxAPI.xml @@ -0,0 +1,58 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="VirtualBoxAPI"> + + <title>&product-name; Programming Interfaces</title> + + <para> + &product-name; comes with comprehensive support for third-party + developers. The so-called <emphasis>Main API</emphasis> of + &product-name; exposes the entire feature set of the virtualization + engine. It is completely documented and available to anyone who + wishes to control &product-name; programmatically. + </para> + + <para> + The Main API is made available to C++ clients through COM on Windows + hosts or XPCOM on other hosts. Bridges also exist for SOAP, Java and + Python. + </para> + + <para> + All programming information such as documentation, reference + information, header and other interface files, as well as samples + have been split out to a separate <emphasis role="bold">Software + Development Kit (SDK)</emphasis>. The SDK is available for download + from + <ulink url="http://www.virtualbox.org" />. + In particular, the SDK comes with a Programming Guide and Reference + manual in PDF format. This manual contains, among other things, the + information that was previously in this chapter of the User Manual. + </para> + +</chapter> diff --git a/doc/manual/htmlhelp-qthelp.py b/doc/manual/htmlhelp-qthelp.py new file mode 100755 index 00000000..dd0405b8 --- /dev/null +++ b/doc/manual/htmlhelp-qthelp.py @@ -0,0 +1,281 @@ +#!/usr/bin/python3 + +# $Id: htmlhelp-qthelp.py $ +## @file +# A python script to create a .qhp file out of a given htmlhelp +# folder. Lots of things about the said folder is assumed. Please +# see the code and inlined comments. + +import sys, getopt +import os.path +import re +import codecs +import logging + +if sys.version_info >= (3, 0): + from html.parser import HTMLParser +else: + from HTMLParser import HTMLParser + + +__copyright__ = \ +""" +Copyright (C) 2006-2023 Oracle and/or its affiliates. + +This file is part of VirtualBox base platform packages, as +available from https://www.virtualbox.org. + +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, in version 3 of the +License. + +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, see <https://www.gnu.org/licenses>. + +SPDX-License-Identifier: GPL-3.0-only +""" + +# number of opened and not yet closed section tags of toc section +open_section_tags = 0 + +html_files = [] + +# use html_parser stuff to collect <a name tags +def create_keywords_section(folder): + keywords_section_lines = ['<keywords>'] + for html_file_name in html_files: + full_html_path = os.path.join(folder, html_file_name) + file_content = codecs.open(full_html_path, encoding='iso-8859-1').read() + + class html_parser(HTMLParser): + def __init__(self): + HTMLParser.__init__(self) + self.a_tag=[] + def handle_starttag(self, tag, attributes): + if tag != 'div' and tag != 'a': + return + if tag == 'a': + for a in attributes: + if a[0] == 'name': + self.a_tag.append(a[1]) + + parser = html_parser() + parser.feed(file_content) + for k in parser.a_tag: + line = '<keyword name="' + k + '" id="' + k + '" ref="' + html_file_name + '#' + k + '"/>' + keywords_section_lines.append(line); + keywords_section_lines.append('</keywords>') + return keywords_section_lines + +# find the png files under /images folder and create a part of the +# qhelp project file with <file> tags +def create_image_list(folder): + image_folder_name = 'images' + image_files_list = [] + # Look for 'images' sub folder + subdirs = [x[0] for x in os.walk(folder)] + full_folder_path = os.path.join(folder, image_folder_name) + if full_folder_path not in subdirs: + logging.error('Image subfolder "%s" is not found under "%s".', image_folder_name, folder) + return image_files_list; + png_files = [] + for f in os.listdir(full_folder_path): + png_files.append(image_folder_name + '/' + f) + image_files_list.append('<file>images/' + f + '</file>') + return image_files_list + +# open htmlhelp.hhp files and read the list of html files from there +def create_html_list(folder): + global html_files + file_name = 'htmlhelp.hhp' + html_file_lines = [] + if not file_name in os.listdir(folder): + logging.error('Could not find the file "%s" in "%s"', file_name, folder) + return html_file_lines + full_path = os.path.join(folder, 'htmlhelp.hhp') + file = codecs.open(full_path, encoding='iso-8859-1') + + lines = file.readlines() + file.close() + # first search for the [FILES] marker then collect .html lines + marker_found = 0 + for line in lines: + if '[FILES]' in line: + marker_found = 1 + continue + if marker_found == 0: + continue + if '.html' in line: + html_file_lines.append('<file>' + line.strip('\n') + '</file>') + html_files.append(line.strip('\n')) + return html_file_lines + + +def create_files_section(folder): + files_section_lines = ['<files>'] + files_section_lines += create_image_list(folder) + files_section_lines += create_html_list(folder) + files_section_lines.append('</files>') + return files_section_lines + +def parse_param_tag(line): + label = 'value="' + start = line.find(label); + if start == -1: + return '' + start += len(label) + end = line.find('"', start) + if end == -1: + return ''; + return line[start:end] + +# look at next two lines. they are supposed to look like the following +# <param name="Name" value="Oracle VM VirtualBox"> +# <param name="Local" value="index.html"> +# parse out value fields and return +# title="Oracle VM VirtualBox" ref="index.html +def parse_object_tag(lines, index): + result='' + if index + 2 > len(lines): + logging.warning('Not enough tags after this one "%s"',lines[index]) + return result + if not re.match(r'^\s*<param', lines[index + 1], re.IGNORECASE) or \ + not re.match(r'^\s*<param', lines[index + 2], re.IGNORECASE): + logging.warning('Skipping the line "%s" since next two tags are supposed to be param tags', lines[index]) + return result + title = parse_param_tag(lines[index + 1]) + ref = parse_param_tag(lines[index + 2]) + global open_section_tags + if title and ref: + open_section_tags += 1 + result = '<section title="' + title + '" ref="' + ref + '">' + else: + logging.warning('Title or ref part is empty for the tag "%s"', lines[index]) + return result + +# parse any string other than staring with <OBJECT +# decide if <session tag should be closed +def parse_non_object_tag(lines, index): + if index + 1 > len(lines): + return '' + global open_section_tags + if open_section_tags <= 0: + return '' + # replace </OBJECT with </section only if the next tag is not <UL + if re.match(r'^\s*</OBJECT', lines[index], re.IGNORECASE): + if not re.match(r'^\s*<UL', lines[index + 1], re.IGNORECASE): + open_section_tags -= 1 + return '</section>' + elif re.match(r'^\s*</UL', lines[index], re.IGNORECASE): + open_section_tags -= 1 + return '</section>' + return '' + +def parse_line(lines, index): + result='' + + # if the line starts with <OBJECT + if re.match(r'^\s*<OBJECT', lines[index], re.IGNORECASE): + result = parse_object_tag(lines, index) + else: + result = parse_non_object_tag(lines, index) + return result + +# parse toc.hhc file. assuming all the relevant information +# is stored in tags and attributes. whatever is outside of +# <... > pairs is filtered out. we also assume < ..> are not nested +# and each < matches to a > +def create_toc(folder): + toc_file = 'toc.hhc' + content = [x[2] for x in os.walk(folder)] + if toc_file not in content[0]: + logging.error('Could not find toc file "%s" under "%s"', toc_file, folder) + return + full_path = os.path.join(folder, toc_file) + file = codecs.open(full_path, encoding='iso-8859-1') + content = file.read() + file.close() + # convert the file string into a list of tags there by eliminating whatever + # char reside outside of tags. + char_pos = 0 + tag_list = [] + while char_pos < len(content): + start = content.find('<', char_pos) + if start == -1: + break + end = content.find('>', start) + if end == -1 or end >= len(content) - 1: + break + char_pos = end + tag_list.append(content[start:end +1]) + + # # insert new line chars. to make sure each line includes at most one tag + # content = re.sub(r'>.*?<', r'>\n<', content) + # lines = content.split('\n') + toc_string_list = ['<toc>'] + index = 0 + for tag in tag_list: + str = parse_line(tag_list, index) + if str: + toc_string_list.append(str) + index += 1 + toc_string_list.append('</toc>') + toc_string = '\n'.join(toc_string_list) + + return toc_string_list + +def usage(arg): + print('htmlhelp-qthelp.py -d <helphtmlfolder> -o <outputfilename>') + sys.exit() + +def main(argv): + helphtmlfolder = '' + output_filename = '' + try: + opts, args = getopt.getopt(sys.argv[1:],"hd:o:") + except getopt.GetoptError as err: + print(err) + usage(2) + for opt, arg in opts: + if opt == '-h': + usage(0) + elif opt in ("-d"): + helphtmlfolder = arg + elif opt in ("-o"): + output_filename = arg + + # check supplied helphtml folder argument + if not helphtmlfolder: + logging.error('No helphtml folder is provided. Exiting') + usage(2) + if not os.path.exists(helphtmlfolder): + logging.error('folder "%s" does not exist. Exiting', helphtmlfolder) + usage(2) + helphtmlfolder = os.path.normpath(helphtmlfolder) + + # check supplied output file name + if not output_filename: + logging.error('No filename for output is given. Exiting') + usage(2) + + out_xml_lines = ['<?xml version="1.0" encoding="UTF-8"?>', \ + '<QtHelpProject version="1.0">' , \ + '<namespace>org.virtualbox</namespace>', \ + '<virtualFolder>doc</virtualFolder>', \ + '<filterSection>'] + out_xml_lines += create_toc(helphtmlfolder) + create_files_section(helphtmlfolder) + out_xml_lines += create_keywords_section(helphtmlfolder) + out_xml_lines += ['</filterSection>', '</QtHelpProject>'] + + out_file = open(output_filename, 'wb') + out_file.write('\n'.join(out_xml_lines).encode('utf8')) + out_file.close() + +if __name__ == '__main__': + main(sys.argv[1:]) diff --git a/doc/manual/ru_RU/docbook-refentry-link-replacement-xsl-gen.xsl b/doc/manual/ru_RU/docbook-refentry-link-replacement-xsl-gen.xsl new file mode 100644 index 00000000..4c94f59c --- /dev/null +++ b/doc/manual/ru_RU/docbook-refentry-link-replacement-xsl-gen.xsl @@ -0,0 +1,44 @@ +<?xml version="1.0"?> +<!-- + docbook-refentry-link-replacement-xsl-gen.xsl: + XSLT stylesheet for generate a stylesheet that replaces links + to the user manual in the manpages. +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<xsl:stylesheet + version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:str="http://xsltsl.org/string" + > + + <xsl:import href="../docbook-refentry-link-replacement-xsl-gen.xsl"/> + + <!-- Translated strings --> + <xsl:variable name="sChapter" select="'глава'"/> + <xsl:variable name="sSection" select="'секция'"/> + <xsl:variable name="sOfManual" select="'руководства пользователя'"/> + <xsl:variable name="sInManual" select="'руководства пользователя'"/> + +</xsl:stylesheet> + diff --git a/doc/manual/ru_RU/docbook-refentry-to-C-help.xsl b/doc/manual/ru_RU/docbook-refentry-to-C-help.xsl new file mode 100644 index 00000000..362d7bd8 --- /dev/null +++ b/doc/manual/ru_RU/docbook-refentry-to-C-help.xsl @@ -0,0 +1,42 @@ +<?xml version="1.0"?> +<!-- + docbook-refentry-to-manual-sect1.xsl: + XSLT stylesheet for nicking the refsynopsisdiv bit of a + refentry (manpage) for use in the command overview section + in the user manual. +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<xsl:stylesheet + version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:str="http://xsltsl.org/string" + > + + <xsl:import href="../docbook-refentry-to-C-help.xsl"/> + + <!-- Translated strings --> + <xsl:variable name="sUsage" select="'Использование'"/> + <xsl:variable name="sUsageUnderscore" select="'============='"/> + +</xsl:stylesheet> diff --git a/doc/manual/ru_RU/man_VBoxManage-adoptstate.xml b/doc/manual/ru_RU/man_VBoxManage-adoptstate.xml new file mode 100644 index 00000000..60c798f1 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-adoptstate.xml @@ -0,0 +1,110 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage adoptstate +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-adoptstate" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage adoptstate</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-adoptstate</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-adoptstate</refname> + <refpurpose>изменение состояния виртуальной машины на основе файла сохраненного состояния</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-adoptstate"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage adoptstate</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="req"><replaceable>имя-файла-состояния</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage adoptstate</command> позволяет изменить + состояние виртуальной машины (ВМ) на состояние, описываемое в файле + сохраненного состояния (<filename>.sav</filename>). Это действие + упоминается как ВМ, <emphasis>принимающая</emphasis> файл сохраненного + состояния. Файл сохраненного состояния должен быть отдельным от + конфигурации ВМ. + </para> + <para> + Когда ВМ запускается после данной команды, ВМ восстанавливает свое + состояние из указанного файла. + </para> + <para> + Используйте эту команду только для нестандартного развертывания ПО. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>имя-ВМ</replaceable></term> + <listitem><para> + Указывает Универсальный Уникальный Идентификатор (UUID) или + имя ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>имя-файла-состояния</replaceable></term> + <listitem><para> + Указывает имя файла сохраненного состояния. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда запускает ВМ с именем <literal>vm2</literal>, используя + файл сохраненного состояния с именем <filename>mystate.sav</filename>. + </para> +<screen>$ VBoxManage adoptstate vm2 /home/user/mystate.sav</screen> + </refsect1> + + <refsect1> + <title>Смотрите Также</title> + <para> + <xref linkend="vboxmanage-discardstate"/> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-bandwidthctl.xml b/doc/manual/ru_RU/man_VBoxManage-bandwidthctl.xml new file mode 100644 index 00000000..ca2ecca9 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-bandwidthctl.xml @@ -0,0 +1,305 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage bandwidthctl +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-bandwidthctl" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage bandwidthctl</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-bandwidthctl</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-bandwidthctl</refname> + <refpurpose>управление группами полосы пропускания</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-bandwidthctl-add"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage bandwidthctl</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">add</arg> + <arg choice="req"><replaceable>имя-группы-полосы-пропускания</replaceable></arg> + <arg choice="req">--limit=<replaceable>лимит-полосы-пропускания</replaceable>[k|m|g|K|M|G]</arg> + <arg choice="req">--type=disk|network</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-bandwidthctl-list"> + <command>VBoxManage bandwidthctl</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">list</arg> + <arg>--machinereadable</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-bandwidthctl-remove"> + <command>VBoxManage bandwidthctl</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">remove</arg> + <arg choice="req"><replaceable>имя-группы-полосы-пропускания</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-bandwidthctl-set"> + <command>VBoxManage bandwidthctl</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">set</arg> + <arg choice="req"><replaceable>имя-группы-полосы-пропускания</replaceable></arg> + <arg choice="req">--limit=<replaceable>лимит-полосы-пропускания</replaceable>[k|m|g|K|M|G]</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage bandwidthctl</command> позволяет управлять + группами полосы пропускания для виртуальных машин (ВМ). Группа полосы + пропускания указывает лимит полосы пропускания для дисков или сетевых + адаптеров ВМ. + </para> + <para> + Обратите внимание, что лимит полосы пропускания сети применяется только + к исходящему траффику ВМ. Входящий траффик не ограничивается. + </para> + <refsect2 id="vboxmanage-bandwidthctl-add"> + <title>Создание группы полосы пропускания</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage bandwidthctl add</command> создает группу + полосы пропускания для указанной ВМ. Вы должны указать назначение + группы полосы пропускания: для дисков или сетей, а также указать + лимит полосы пропускания. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>имя-ВМ</replaceable></term> + <listitem><para> + Указывает Универсальный Уникальный Идентификатор (UUID) или + имя ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option><replaceable>имя-группы-полосы-пропускания</replaceable></option></term> + <listitem><para> + Указывает имя группы полосы пропускания. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--type=disk|network</option></term> + <listitem><para> + Указывает тип группы полосы пропускания: + <literal>disk</literal> и <literal>network</literal>. + Для дополнительной информации смотрите + <xref linkend="storage-bandwidth-limit" /> или <xref linkend="network_bandwidth_limit" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--limit=<replaceable>лимит-полосы-пропускания</replaceable>[k|m|g|K|M|G]</option></term> + <listitem><para> + Указывает лимит для группы полосы пропускания. По умолчанию, + указывается в мегабайтах в секунду. Можно изменить это значение + пока ВМ работает. + </para><para> + Можно изменить единицы измерения, добавляя следующие спецификаторы + к лимиту полосы пропускания: + </para><itemizedlist> + <listitem><para> + <literal>k</literal> – килобит в секунду + </para></listitem> + <listitem><para> + <literal>m</literal> – мегабит в секунду + </para></listitem> + <listitem><para> + <literal>g</literal> – гигабит в секунду + </para></listitem> + <listitem><para> + <literal>K</literal> – килобайт в секунду + </para></listitem> + <listitem><para> + <literal>M</literal> – мегабайт в секунду + </para></listitem> + <listitem><para> + <literal>G</literal> – гигабайт в секунду + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-bandwidthctl-list"> + <title>Отображение групп полосы пропускания</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage bandwidthctl list</command> показывает + все группы полосы пропускания, определенные для указанной ВМ. + Используйте опцию <option>--machinereadable</option> для вывода + в машино-читаемом формате, который использует пары имя-значение. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>имя-ВМ</replaceable></term> + <listitem><para> + Указывает UUID или имя ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--machinereadable</option></term> + <listitem><para> + Выводит информацию о группах полосы пропускания в виде + пар имя-значение. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-bandwidthctl-remove"> + <title>Удаление группы полосы пропускания</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage bandwidthctl remove</command> удаляет + группу полосы пропускания. + </para> + <note> + <para> + Для успешного удаления группы полосы пропускания, убедитесь + что она не ссылается на диск или адаптер работающей ВМ. + </para> + </note> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>имя-ВМ</replaceable></term> + <listitem><para> + Указывает UUID или имя ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option><replaceable>имя-группы-полосы-пропускания</replaceable></option></term> + <listitem><para> + Указывает имя группы полосы пропускания. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-bandwidthctl-set"> + <title>Изменение лимита группы полосы пропускания</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage bandwidthctl set</command> изменяет + лимит группы полосы пропускания. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>имя-ВМ</replaceable></term> + <listitem><para> + Указывает UUID или имя ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option><replaceable>bandwidth-group-name</replaceable></option></term> + <listitem><para> + Указывает имя группы полосы пропускания. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--limit=<replaceable>лимит-полосы-пропускания</replaceable>[k|m|g|K|M|G]</option></term> + <listitem><para> + Указывает лимит для группы полосы пропускания. По умолчанию, + указывается в мегабайтах в секунду. Можно изменить это значение + пока ВМ работает. + </para><para> + Можно изменить единицы измерения, добавляя следующие спецификаторы + к лимиту полосы пропускания: + </para><itemizedlist> + <listitem><para> + <literal>k</literal> – килобит в секунду + </para></listitem> + <listitem><para> + <literal>m</literal> – мегабит в секунду + </para></listitem> + <listitem><para> + <literal>g</literal> – гигабит в секунду + </para></listitem> + <listitem><para> + <literal>K</literal> – килобайт в секунду + </para></listitem> + <listitem><para> + <literal>M</literal> – мегабайт в секунду + </para></listitem> + <listitem><para> + <literal>G</literal> – гигабайт в секунду + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + Следующий пример показывает, как использовать команду + <command>VBoxManage bandwidthctl</command> для создания группы + полосы пропускания <literal>Limit</literal> с лимитом в 20 Мбит/с. + Затем используется команда <command>VBoxManage modifyvm</command> + для назначения этой группы первому и второму адаптерам ВМ + <literal>vm1</literal>. + </para> +<screen>$ VBoxManage bandwidthctl "vm1" add Limit --type network --limit 20m +$ VBoxManage modifyvm "vm1" --nicbandwidthgroup1 Limit +$ VBoxManage modifyvm "vm1" --nicbandwidthgroup2 Limit</screen> + <para> + Можно динамически менять лимит группы полосы пропускания пока + ВМ работает. Следующий пример показывает как изменить лимит + для группы полосы пропускания <literal>Limit</literal> с 20 + Мбит/с в 100 кбит/с: + </para> +<screen>$ VBoxManage bandwidthctl "vm1" set Limit --limit 100k</screen> + <para> + Следующая команда отключает ограничения для всех адаптеров в + группе полосы пропускания <literal>Limit</literal> путем установки + лимита в ноль (<literal>0</literal>): + </para> +<screen>$ VBoxManage bandwidthctl "vm1" set Limit --limit 0</screen> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-checkmediumpwd.xml b/doc/manual/ru_RU/man_VBoxManage-checkmediumpwd.xml new file mode 100644 index 00000000..9c51d56c --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-checkmediumpwd.xml @@ -0,0 +1,111 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage checkmediumpwd +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-checkmediumpwd" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage checkmediumpwd</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-checkmediumpwd</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-checkmediumpwd</refname> + <refpurpose>проверка пароля носителя или образа диска, зашифрованного DEK</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-checkmediumpwd"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage checkmediumpwd</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-файла</replaceable></arg> + </group> + <arg choice="req"><replaceable>файл-с-паролем</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage checkmediumpwd</command> проверяет + текущий пароль, используемый для шифрования носителя или образа + диска, зашифрованными DEK. Смотрите <xref linkend="diskencryption-encryption" />. + </para> + <para> + Ответ команды показывает корректен ли указанный пароль. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>имя-файла</replaceable></term> + <listitem><para> + Задает Уникальный Универсальный Идентификатор (UUID) или + абсолютный путь к носителю или образу. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>файл-с-паролем</replaceable></term> + <listitem><para> + Указывает идентификатор пароля для проверки. Идентификатор + пароля может быть указан через абсолютный путь к файлу, + содержащему пароль, или через дефис (<literal>-</literal>). + Во втором случае будет предложено ввести пароль. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующий пример проверяет пароль шифрования у образа диска + с именем <filename>ol7u4-1.vdi</filename>. Идентификатор + пароля - это файл с именем <filename>pwfile</filename>. + </para> + <para> + Команда возвращает сообщение, показывающее что пароль корректен. + </para> +<screen>$ VBoxManage checkmediumpwd "$HOME/VirtualBox VMs/ol7u4/ol7u4-1.vdi" /home/user/pwfile + Указанный пароль корректен</screen> + </refsect1> + + <refsect1> + <title>Смотрите также</title> + <para> + <xref linkend="vboxmanage-encryptmedium" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-clonemedium.xml b/doc/manual/ru_RU/man_VBoxManage-clonemedium.xml new file mode 100644 index 00000000..3df62365 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-clonemedium.xml @@ -0,0 +1,214 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage clonemedium +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-clonemedium" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage clonemedium</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-clonemedium</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-clonemedium</refname> + <refpurpose>создание клона носителя</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-clonemedium"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage clonemedium</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>носитель-источник</replaceable></arg> + </group> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>носитель-назначения</replaceable></arg> + </group> + <group> + <arg choice="plain">disk</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">floppy</arg> + </group> + <arg>--existing</arg> + <arg>--format=<group choice="plain"> + <arg choice="plain">VDI</arg> + <arg choice="plain">VMDK</arg> + <arg choice="plain">VHD</arg> + <arg choice="plain">RAW</arg> + <arg choice="plain"><replaceable>другие</replaceable></arg> + </group></arg> + <arg>--variant=Standard,Fixed,Split2G,Stream,ESX</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage clonemedium</command> позволяет клонировать + существующий носитель (виртуальный диск, DVD, или флоппи). В основном, + это файл образа. Оригинальный образ от клонированного отличаются + только Уникальным Универсальным Идентификатором (UUID). + </para> + <para> + Можно использовать Менеджер Виртуальных Носителей для передачи + клонированного носителя на другой хост или импортировать его в &product-name;. + Смотрите <xref linkend="virtual-media-manager" /> и <xref linkend="cloningvdis" />. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>носитель-источник</replaceable></term> + <listitem><para> + Указывает UUID или абсолютное или относительное имя файла + носителя-источника для клонирования. UUID можно указать + только если он зарегистрирован. Используйте команду <command>VBoxManage + list hdds</command> для отображения зарегистрированных образов. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>носитель-назначения</replaceable></term> + <listitem><para> + Указывает UUID или абсолютное или относительное имя файла + носителя назначения (клонированного носителя). UUID можно + указать только если он зарегистрирован. Используйте + команду <command>VBoxManage list hdds</command> для отображения + зарегистрированных образов. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>disk</literal> | <literal>dvd</literal> | <literal>floppy</literal></term> + <listitem><para> + Указывает тип носителя для клонирования. Допустимые значения: + <literal>disk</literal>, <literal>dvd</literal> и + <literal>floppy</literal>. <literal>disk</literal> используется + по умолчанию. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--existing</option></term> + <listitem><para> + Производит операцию клонирования путем перезаписывания + носителя назначения. В результате записывается только + та часть носителя-источника, которая умещается в + существующий носитель назначения. + </para><para> + Если носитель назначения меньше источника, копируется + только порция источника размером с носитель назначения. + </para><para> + Если носитель назначения больше источника, оставшаяся + часть носителя назначения остается неизменной. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--format</option></term> + <listitem><para> + Указывает формат файла носителя назначения, если он + отличается от источника. Допустимые значения: + <literal>VDI</literal>, <literal>VMDK</literal>, + <literal>VHD</literal>, <literal>RAW</literal> и + <replaceable>другие</replaceable>. + </para><remark> + Какие могут быть быть <replaceable>другие</replaceable> + форматы файлов? + </remark></listitem> + </varlistentry> + <varlistentry> + <term><option>--variant=Standard,Fixed,Split2G,Stream,ESX</option></term> + <listitem><para> + Указывает варианты формата файла носителя назначения, + указанные через запятую. Допустимы следующие значения: + </para><itemizedlist> + <listitem><para> + <literal>Standard</literal> является типом образа диска + по умолчанию с динамически изменяемым размером файла. + </para></listitem> + <listitem><para> + <literal>Fixed</literal> использует образ диска + фиксированного размера. + </para></listitem> + <listitem><para> + <literal>Split2G</literal> показывает, что образ диска + делится на сегменты по 2 ГБ. Это значение только для + VMDK. + </para></listitem> + <listitem><para> + <literal>Stream</literal> оптимизирует образ диска + для загрузки. Это значение только для VMDK. + </para></listitem> + <listitem><para> + <literal>ESX</literal> используется на некоторых + продуктах VMWare. Это значение только для VMDK. + </para></listitem> + </itemizedlist><para> + Заметим, что не все комбинации вариантов допустимы. + Указание неполного списка вариантов приводит к сообщению + об ошибке. + </para></listitem> + </varlistentry> + </variablelist> + <note> + <para> + Для совместимости с ранними версиями &product-name;, можно + использовать команды <command>clonevdi</command> и + <command>clonehd</command> вместо команды + <command>clonemedium</command>. + </para> + </note> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда создает клон файла образа диска + <filename>disk01.vdi</filename>. Клон называется + <filename>disk02.vdi</filename>. + </para> +<screen>$ VBoxManage clonemedium disk01.vdi disk02.vdi</screen> + <para> + Следующая команда создает клон файла образа диска + <filename>disk01.vdi</filename>. Клон имеет формат + VMDK и называется <filename>disk02.vmdk</filename>. + </para> +<screen>$ VBoxManage clonemedium disk01.vdi disk02.vmdk --format VMDK</screen> + </refsect1> + + <refsect1> + <title>Смотрите также</title> + <para> + <xref linkend="vboxmanage-list" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-clonevm.xml b/doc/manual/ru_RU/man_VBoxManage-clonevm.xml new file mode 100644 index 00000000..c65763c5 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-clonevm.xml @@ -0,0 +1,270 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage clonevm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-clonevm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage clonevm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-clonevm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-clonevm</refname> + <refpurpose>создание клона существующей виртуальной машины &product-name;</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-clonevm"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage clonevm</command> + <arg choice="req"><replaceable>имя-ВМ|uuid</replaceable></arg> + + <arg>--basefolder=<replaceable>основная-папка</replaceable></arg> + + <arg rep="repeat">--groups=<replaceable>группа</replaceable>,</arg> + + <group choice='opt'> + <arg choice='plain'>--mode=machine</arg> + <arg choice='plain'>--mode=machinechildren</arg> + <arg choice='plain'>--mode=all</arg> + </group> + + <arg>--name=<replaceable>имя</replaceable></arg> + + <arg rep="repeat">--options=<replaceable>опция</replaceable>,</arg> + + <arg>--register</arg> + + <arg>--snapshot=<replaceable>имя-снимка</replaceable></arg> + + <arg>--uuid=<replaceable>uuid</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage clonevm</command> создает клон существующей + виртуальной машины (ВМ). Клон может быть либо полной копией ВМ + либо связанной копией. + </para> + <para> + Вы должны указать имя или универсальный уникальный идентификатор + (UUID) клонируемой машины. + </para> + </refsect1> + + <refsect1> + <title>Командные операнды и опции</title> + <para> + Следующий список описывает операнды и опции, которые можно использовать + с командой <command>VBoxManage clonevm</command>: + </para> + <variablelist> + <varlistentry> + <term><replaceable>имя-ВМ|uuid</replaceable></term> + <listitem><para> + Указывает имя или UUID клонируемой ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--basefolder=<replaceable>основная-папка</replaceable></option></term> + <listitem><para> + Указывает имя папки, в которую сохраняется конфигурация + новой ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--groups=<replaceable>группа</replaceable>,...</option></term> + <listitem><para> + Добавляет клон в группу или в группы. Несколько групп + указываются через запятую. + </para><para> + Обратите внимание, что каждая группа идентифицируется по ID + группы, начинающийся с символа <computeroutput>/</computeroutput>, + поэтому группы могут быть вложенные. По умолчанию, клон + всегда добавляется в группу <computeroutput>/</computeroutput>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mode=machine|machineandchildren|all</option></term> + <listitem><para> + Указывает режим клонирования: + </para><itemizedlist> + <listitem><para> + Режим <computeroutput>machine</computeroutput> клонирует + текущее состояние существующей ВМ без снимков. Это + режим по умолчанию. + </para></listitem> + <listitem><para> + Режим <computeroutput>machineandchildren</computeroutput> + клонирует снимок, указанный через опцию + <option>--snapshot</option>, и все его дочерние + снимки. + </para></listitem> + <listitem><para> + Режим <computeroutput>all</computeroutput> клонирует + все снимки и текущее состояние существующей ВМ. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--name=<replaceable>имя</replaceable></option></term> + <listitem><para> + Указывает имя для новой ВМ. Значение по умолчанию - это + <computeroutput>Копия <replaceable>исходное-имя</replaceable></computeroutput>, + где <replaceable>исходное-имя</replaceable> - это имя + исходной ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--options=<replaceable>опция</replaceable>,...</option></term> + <listitem><para> + Указывает как создать новый клон.</para> + <para>Аргумент <option>--options</option> может быть использован + несколько раз для указания нескольких опций или опции могут быть + указаны списком через запятую. Опции не чувствительны к регистру.</para> + <para>Распознаются следующие опции (не чувствительны к регистру):</para> + <variablelist> + <varlistentry> + <term><option>Link</option></term> + <listitem><para> + Создает связанный клон только из снимка. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>KeepAllMACs</option></term> + <listitem><para> + Указывает, что новый клон использует MAC адреса + всех сетевых карт существующей ВМ. + </para><para> + Если вы не укажете эту опцию или опцию + <option>--options=keepnatmacs</option>, то + МАС адреса каждой сетевой карты новой ВМ + инициализируются новыми значениями. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>KeepNATMACs</option></term> + <listitem><para> + Указывает, что новый клон использует MAC адреса + всех сетевых карт существующей ВМ, если используется + сеть типа NAT. + </para><para> + Если вы не укажете эту опцию или опцию + <option>KeepAllMACs</option>, то МАС адреса каждой + сетевой карты новой ВМ инициализируются новыми значениями. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>KeepDiskNames</option></term> + <listitem><para> + Указывает, что новый клон использует те же имена + образов дисков что и существующая ВМ. По умолчанию + образы дисков переименовываются. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>KeepHwUUIDs</option></term> + <listitem><para> + Указывает, что новый клон использует идентификаторы + аппаратного обеспечения из существующей ВМ. По + умолчанию назначаются новые UUID. + </para></listitem> + </varlistentry> + </variablelist></listitem> + </varlistentry> + <varlistentry> + <term><option>--register</option></term> + <listitem><para> + Автоматически регистрирует новый клон в &product-name;. + Позже можно зарегистрировать новую ВМ вручную с помощью + команды <command>VBoxManage registervm</command>. + Смотрите <xref linkend="vboxmanage-registervm" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--snapshot=<replaceable>имя-снимка</replaceable></option></term> + <listitem><para> + Указывает снимок, являющийся основой для новой ВМ. По + умолчанию клон создается из текущего состояния указанной ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Указывает UUID для новой ВМ. Убедитесь, что ID является + уникальным в экземпляре &product-name; если вы решили + зарегистрировать новую ВМ. По умолчанию, &product-name; + сам назначает новый UUID. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Примеры</title> + <para> + Следующая команда создает и регистрирует точный клон ВМ + <computeroutput>ol7</computeroutput>. Клон называется + <computeroutput>ol7-dev-001</computeroutput>. + </para> + <para> + Новый клон включает все снимки исходной ВМ. Новая ВМ использует + те же самые MAC адреса всех сетевых интерфейсов, имена дисков + и UUIDы исходной ВМ. + </para> +<screen> +$ VBoxManage clonevm ol7 --name="ol7-dev-001" --register --mode=all \ + --options=keepallmacs --options=keepdisknames --options=keephwuuids +</screen> + <para> + Следующая команда создает и регистрирует клон снимка + <computeroutput>Снимок 1</computeroutput> ВМ + <computeroutput>ol7</computeroutput>. Клон называется + <computeroutput>ol7-dev-002</computeroutput>. + </para> +<screen> +$ VBoxManage clonevm ol7 --name="ol7-dev-002" --register --snapshot="Снимок 1" +</screen> + </refsect1> + + <refsect1> + <title>Смотрите также</title> + <para> + <xref linkend="vboxmanage-registervm" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-closemedium.xml b/doc/manual/ru_RU/man_VBoxManage-closemedium.xml new file mode 100644 index 00000000..8ef5232a --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-closemedium.xml @@ -0,0 +1,121 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage closemedium +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-closemedium" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage closemedium</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-closemedium</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-closemedium</refname> + <refpurpose>удаляет образ жесткого диска, DVD, или флоппи из реестра носителей</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-closemedium"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage closemedium</command> + <group> + <arg choice="plain">disk</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">floppy</arg> + </group> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-файла</replaceable></arg> + </group> + <arg>--delete</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage closemedium</command> удаляет образ + жесткого диска, DVD или флоппи из списка известных носителей, + используемых &product-name;. После выполнения данной команды + указанный образ нельзя будет выбрать в Менеджере Виртуальных + Носителей. + </para> + <para> + Для использования этой команды образ не должен быть подключен + к какой-либо ВМ. + </para> + <para> + Дополнительно можно запросить удаление образа. + </para> + <variablelist> + <varlistentry> + <term>disk|dvd|floppy</term> + <listitem><para> + Указывает тип носителя. Допустимые значения: + <literal>disk</literal> (жесткий диск), + <literal>dvd</literal> или <literal>floppy</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>имя-файла</replaceable></term> + <listitem><para> + Указывает Универсальный Уникальный Идентификатор (UUID) + или абсолютный путь к носителю или образу. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--delete</option></term> + <listitem><para> + Удаляет файл образа. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда удаляет файл образа диска с именем + <filename>disk01.vdi</filename> из реестра. + </para> +<screen>$ VBoxManage closemedium disk01.vdi</screen> + <para> + Следующая команда удаляет файл образа диска с именем + <filename>disk01.vdi</filename> из реестра и удаляет + файл образа. + </para> +<screen>$ VBoxManage closemedium disk01.vdi --delete</screen> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-cloud.xml b/doc/manual/ru_RU/man_VBoxManage-cloud.xml new file mode 100644 index 00000000..318fa5df --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-cloud.xml @@ -0,0 +1,655 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage cloud +--> +<!-- + Copyright (C) 2018-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-cloud" lang="en"> + <refentryinfo> + <title>VBoxManage cloud</title> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-cloud</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="manual">Oracle VM VirtualBox</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>VBoxManage-cloud</refname> + <refpurpose>Управление облачными сущностями</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <!-- Cloud list --> + <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <cmdsynopsis id="synopsis-vboxmanage-cloudlist-instances"> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <sbr/> + <arg choice="plain">list</arg> + <arg choice="plain">instances</arg> + <arg>--state=<replaceable>строка</replaceable></arg> + <arg>--compartment-id=<replaceable>строка</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudlist-images"> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <sbr/> + <arg choice="plain">list</arg> + <arg choice="plain">images</arg> + <arg choice="req">--compartment-id=<replaceable>строка</replaceable></arg> + <arg>--state=<replaceable>строка</replaceable></arg> + </cmdsynopsis> + + <!-- Cloud instance commands --> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-create" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <sbr/> + <arg choice="plain">instance</arg> + <arg choice="plain">create</arg> + <arg choice="req">--domain-name=<replaceable>имя</replaceable></arg> + <group choice="req"> + <arg choice="req">--image-id=<replaceable>id</replaceable></arg> + <arg choice="req">--boot-volume-id=<replaceable>id</replaceable></arg> + </group> + <arg choice="req">--display-name=<replaceable>имя</replaceable></arg> + <arg choice="req">--shape=<replaceable>тип</replaceable></arg> + <arg choice="req">--subnet=<replaceable>id</replaceable></arg> + <arg>--boot-disk-size=<replaceable>размер в ГБ</replaceable></arg> + <arg>--publicip=<replaceable>true/false</replaceable></arg> + <arg>--privateip=<replaceable>IP адрес</replaceable></arg> + <arg rep="repeat">--public-ssh-key=<replaceable>ключевая строка</replaceable></arg> + <arg>--launch-mode=<replaceable>NATIVE/EMULATED/PARAVIRTUALIZED</replaceable></arg> + <arg>--cloud-init-script-path=<replaceable>путь к скрипту</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-info" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <sbr/> + <arg choice="plain">instance</arg> + <arg choice="plain">info</arg> + <arg choice="req">--id=<replaceable>уникальный id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-terminate" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <sbr/> + <arg choice="plain">instance</arg> + <arg choice="plain">terminate</arg> + <arg choice="req">--id=<replaceable>уникальный id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-start" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <sbr/> + <arg choice="plain">instance</arg> + <arg choice="plain">start</arg> + <arg choice="req">--id=<replaceable>уникальный id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-pause" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <sbr/> + <arg choice="plain">instance</arg> + <arg choice="plain">pause</arg> + <arg choice="req">--id=<replaceable>уникальный id</replaceable></arg> + </cmdsynopsis> + + <!-- Cloud image commands --> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-create" sepchar=" "> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <sbr/> + <arg choice="plain">image</arg> + <arg choice="plain">create</arg> + <arg choice="req">--display-name=<replaceable>имя</replaceable></arg> + <arg>--bucket-name=<replaceable>имя</replaceable></arg> + <arg>--object-name=<replaceable>имя</replaceable></arg> + <arg>--instance-id=<replaceable>уникальный id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-info" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <sbr/> + <arg choice="plain">image</arg> + <arg choice="plain">info</arg> + <arg choice="req">--id=<replaceable>уникальный id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-delete" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <sbr/> + <arg choice="plain">image</arg> + <arg choice="plain">delete</arg> + <arg choice="req">--id=<replaceable>уникальный id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-import" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <sbr/> + <arg choice="plain">image</arg> + <arg choice="plain">import</arg> + <arg choice="req">--id=<replaceable>уникальный id</replaceable></arg> + <arg>--bucket-name=<replaceable>имя</replaceable></arg> + <arg>--object-name=<replaceable>имя</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-export" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <sbr/> + <arg choice="plain">image</arg> + <arg choice="plain">export</arg> + <arg choice="req">--id=<replaceable>уникальный id</replaceable></arg> + <arg choice="req">--display-name=<replaceable>имя</replaceable></arg> + <arg>--bucket-name=<replaceable>имя</replaceable></arg> + <arg>--object-name=<replaceable>имя</replaceable></arg> + </cmdsynopsis> + + <!-- Cloud network commands --> + <cmdsynopsis id="synopsis-vboxmanage-cloud-network-setup"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <sbr/> + <arg choice="plain">network setup</arg> + <arg choice="req">--local-gateway-iso=<replaceable>путь</replaceable></arg> + <arg>--gateway-os-name=<replaceable>строка</replaceable></arg> + <arg>--gateway-os-version=<replaceable>строка</replaceable></arg> + <arg>--gateway-shape=<replaceable>строка</replaceable></arg> + <arg>--tunnel-network-name=<replaceable>строка</replaceable></arg> + <arg>--tunnel-network-range=<replaceable>строка</replaceable></arg> + <arg>--guest-additions-iso=<replaceable>путь</replaceable></arg> + <arg>--proxy=<replaceable>строка</replaceable></arg> + <arg>--compartment-id=<replaceable>строка</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloud-network-create"> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <sbr/> + <arg choice="plain">network create</arg> + <arg choice="req">--name=<replaceable>строка</replaceable></arg> + <arg choice="req">--network-id=<replaceable>строка</replaceable></arg> + <group> + <arg choice="plain">--enable</arg> + <arg choice="plain">--disable</arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloud-network-update"> + <command>VBoxManage cloud network update</command> + <arg choice="req">--name=<replaceable>строка</replaceable></arg> + <arg>--network-id=<replaceable>строка</replaceable></arg> + <group> + <arg choice="plain">--enable</arg> + <arg choice="plain">--disable</arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloud-network-delete"> + <command>VBoxManage cloud</command> + <arg choice="plain">network delete</arg> + <arg choice="req">--name=<replaceable>строка</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloud-network-info"> + <command>VBoxManage cloud</command> + <arg choice="plain">network info</arg> + <arg choice="req">--name=<replaceable>строка</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + + <!-- Cloud commands common options --> + <refsect2 id="vboxmanage-cloud-common-options"> + <title>Общие параметры</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>Слово "cloud" объединяет все команды, относящиеся к взаимодействию с облаком. Следующие + общие параметры необходимо разместить между "cloud" и последующими подкомандами:</para> + <variablelist> + <varlistentry> + <term>--provider=<replaceable>имя</replaceable></term> + <listitem><para>Короткое имя облачного провайдера.</para></listitem> + </varlistentry> + <varlistentry> + <term>--profile=<replaceable>имя</replaceable></term> + <listitem><para>Имя профиля облака. </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <!-- Cloud list commands --> + <refsect2 id="vboxmanage-cloudlist-instances"> + <title>cloud list instances</title> + <remark role="help-copy-synopsis"/> + <para> + Отображает список экземпляров указанной секции. + </para> + <variablelist> + <varlistentry> + <term>--state<replaceable>"running/paused/terminated"</replaceable></term> + <listitem> + <para>Состояние облачного экземпляра. На данный момент возможны следующие состояния: + "running/paused/terminated". Если состояние не указано, возвращается список экземпляров + со всеми возможными состояниями. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment-id</option></term> + <listitem> + <para>Секция - это логический контейнер, используемый для организации и изоляции + облачных ресурсов. У разных облачных провайдеров эта сущность называется по-разному. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudlist-images"> + <title>cloud list images</title> + <remark role="help-copy-synopsis"/> + <para> + Отображает список образов для указанной секции. + </para> + <variablelist> + <varlistentry> + <term>--state<replaceable>"available/disabled/deleted"</replaceable></term> + <listitem> + <para>Состояние облачного образа. На данный момент возможны следующие состояния: + "available/disabled/deleted". Если состояние не указано, возвращается список + образов со всеми возможными состояниями. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment-id</option></term> + <listitem> + <para>Секция - это логический контейнер, используемый для организации и изоляции + облачных ресурсов. У разных облачных провайдеров эта сущность называется по-разному. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <!-- Cloud instance commands --> + <refsect2 id="vboxmanage-cloudinstance-create"> + <title>cloud instance create</title> + <remark role="help-copy-synopsis"/> + <para> + Создает новый экземпляр в облаке. + Существует два стандартных способа создать экземпляр в облаке: + 1. Создать экземпляр из существующего пользовательского образа. + 2. Создать экземпляр из существующего загрузочного тома. Этот загрузочный том не должен быть подключен + к какому-либо экземпляру. + Для первого способа требуются параметры: image-id, boot-disk-size. + Для второго способа требуются параметры: boot-volume-id. + Остальные параметры являются общими для обоих способов: + display-name, launch-mode, subnet-id, publicIP, privateIP, shape, domain. + </para> + <variablelist> + <varlistentry> + <term><option>--domain-name</option></term><listitem><para>Облачный домен, где создается экземпляр.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--image-id</option></term><listitem><para>Уникальный идентификатор, полностью идентифицирующий пользовательский образ в облаке.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--boot-volume-id</option></term><listitem><para>Уникальный идентификатор, полностью идентифицирующий загрузочный том в облаке.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--display-name</option></term><listitem><para>Имя для нового экземпляра в облаке.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--shape</option></term><listitem><para>Форма экземпляра, определяющая количество ЦПУ и размер RAM памяти.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--subnet</option></term><listitem><para>Уникальный идентификатор, полностью идентифицирующий существующую подсеть в облаке для использования экземпляром.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--boot-disk-size</option></term><listitem><para>Размер загрузочного образа в ГБ. По умолчанию 50 ГБ.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--publicip</option></term><listitem><para>У экземпляра публичный IP или нет.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--privateip</option></term><listitem><para>Приватный IP адрес для созданного экземпляра.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--public-ssh-key</option></term> + <listitem> + <para>Публичный ключ SSH, используемый для подключения к экземпляру через + SSH. Этот параметр может быть указан несколько раз, если нужно указать + несколько ключей, например: "--public-ssh-key=firstSSHKey --public-ssh-key=secondSSHKey". + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--launch-mode</option></term><listitem><para>Наиболее известные значения здесь могут быть EMULATED, NATIVE, PARAVIRTUALIZED.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloud-init-script-path</option></term><listitem><para>Абсолютный путь к пользовательскому скрипту облачной инициализации.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-info"> + <title>cloud instance info</title> + <para> + Отображает информацию об облачном экземпляре с указанным id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Уникальный идентификатор, полностью идентифицирующий экземпляр в облаке.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-terminate"> + <title>cloud instance termination</title> + <para> + Удаляет облачный экземпляр с указанным id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Уникальный идентификатор, полностью идентифицирующий экземпляр в облаке.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-start"> + <title>cloud instance start</title> + <para> + Запускает облачный экземпляр с указанным id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Уникальный идентификатор, полностью идентифицирующий экземпляр в облаке.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-pause"> + <title>cloud instance pause</title> + <para> + Приостанавливает облачный экземпляр с указанным id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Уникальный идентификатор, полностью идентифицирующий экземпляр в облаке.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + + <!-- Cloud image commands --> + <refsect2 id="vboxmanage-cloudimage-create"> + <title>cloud image create</title> + <remark role="help-copy-synopsis"/> + <para> + Создает новый образ в облаке. + Существует два стандартных способа создать образ в облаке: + 1. Создать образ из объекта в облачном хранилище; + 2. Создать образ из существующего облачного экземпляра. + Для первого способа требуются параметры: + bucket-name - имя облачной корзины, где находится объект; + object-name - имя объекта в корзине; + display-name - имя для нового образа в облаке. + Для второго способа требуются параметры: + instance-id - Id экземпляра в облаке; + display-name - имя для нового образа в облаке. + </para> + <variablelist> + <varlistentry> + <term><option>--display-name</option></term><listitem><para>Имя для нового образа в облаке.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bucket-name</option></term><listitem><para>Имя облачной корзине, где находится объект.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--object-name</option></term><listitem><para>Имя объекта в корзине.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--instance-id</option></term><listitem><para>Уникальный идентификатор, полностью идентифицирующий экземпляр в облаке.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-info"> + <title>cloud image info</title> + <remark role="help-copy-synopsis"/> + <para> + Отображает информацию об облачном образе с указанным id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Уникальный идентификатор, полностью идентифицирующий образ в облаке.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-delete"> + <title>cloud image delete</title> + <remark role="help-copy-synopsis"/> + <para> + Удаляет образ с указанным id из облака. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Уникальный идентификатор, полностью идентифицирующий образ в облаке.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-import"> + <title>cloud image import</title> + <remark role="help-copy-synopsis"/> + <para> + Импортирует образ с указанным id из облака на локальный хост. + Результатом является объект в локальной папке "temp" локального хоста. + Возможный подход может состоят из двух основных этапов: + 1. Создать объект из образа в облачном хранилище; + 2. Загрузить объект на локальный хост. + Поэтому, следующие параметры могут потребоваться: + bucket-name - имя облачной корзины где будет создан объект; + object-name - имя объекта в корзине. Если параметр "object-name" отсутствует, будет использовано показанное имя образа. + Если первый этап не нужен, требуется только параметр "id". + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Уникальный идентификатор, полностью идентифицирующий образ в облаке.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bucket-name</option></term><listitem><para>Имя облачной корзины, где будет создан объект.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--object-name</option></term> + <listitem> + <para> + Имя созданного объекта в корзине. У загруженного объекта будет такое же имя. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-export"> + <title>cloud image export</title> + <remark role="help-copy-synopsis"/> + <para> + Экспортирует существующий образ VBox с указанным uuid из локального хоста в облако. + Результатом является новый образ в облаке. + Возможный подход может состоят из двух основных этапов: + 1. Загрузить образ VBox в облачное хранилище; + 2. Создать образ из загруженного объекта. + Поэтому, следующие параметры могут потребоваться: + bucket-name - имя облачной корзины куда будет загружен объект; + object-name - имя объекта в корзине. Если параметр "object-name" отсутствует, будет использован id образа; + display-name - имя для нового образа в облаке. + Если первый этап не нужен, требуются только параметры "id" и "display-name". + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Уникальный идентификатор образа в VirtualBox.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--display-name</option></term><listitem><para>Имя для нового образа в облаке.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bucket-name</option></term><listitem><para>Имя облачной корзины куда будет загружен образ (объект).</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--object-name</option></term><listitem><para>Имя объекта в корзине.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + + <!-- Cloud network commands --> + <refsect2 id="vboxmanage-cloud-network-setup"> + <title>cloud network setup</title> + <remark role="help-copy-synopsis"/> + <para> + Настраивает окружение облачной сети для указанного облачного профиля. + </para> + <variablelist> + <varlistentry> + <term><option>--local-gateway-iso</option></term><listitem><para>Локальный путь к установочному носителю для локального шлюза.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--gateway-os-name</option></term><listitem><para>Имя ОС, используемой для облачного шлюза.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--gateway-os-version</option></term><listitem><para>Версия ОС, используемой для облачного шлюза.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--gateway-shape</option></term><listitem><para>Форма экземпляра, используемая для облачного шлюза.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tunnel-network-name</option></term><listitem><para>Имя VCN/подсети, используемой для туннелирования.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tunnel-network-range</option></term><listitem><para>Диапазон IP адресов, используемый для туннелирования.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--guest-additions-iso</option></term><listitem><para>Локальный путь к установочному носителю Дополнений Гостевой ОС VirtualBox.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--proxy</option></term><listitem><para>URL прокси, используемый в установке локального шлюза.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment-id</option></term><listitem><para>Секция, в которую создается туннель.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloud-network-create"> + <title>cloud network create</title> + <remark role="help-copy-synopsis"/> + <para> + Создает новый дескриптор облачной сети, связанный с существующей облачной подсетью. + </para> + <variablelist> + <varlistentry> + <term><option>--name</option></term><listitem><para>Имя для назначения дескриптору облачной сети.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--network-id</option></term><listitem><para>Уникальный идентификатор существующей подсети в облаке.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--enable</option>, --disable</term> + <listitem><para>Включить или выключить дескриптор сети. Если не указано, сеть будет включена.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloud-network-update"> + <title>cloud network update</title> + <remark role="help-copy-synopsis"/> + <para> + Изменяет существующий дескриптор облачной сети. + </para> + <variablelist> + <varlistentry> + <term><option>--name</option></term><listitem><para>Имя существующего дескриптора облачной сети.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--network-id</option></term><listitem><para>Уникальный идентификатор существующей подсети в облаке.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--enable</option>, --disable</term> + <listitem><para>Включить или выключить дескриптор сети.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloud-network-delete"> + <title>cloud network delete</title> + <remark role="help-copy-synopsis"/> + <para> + Удаляет существующий дескриптор облачной сети. + </para> + <variablelist> + <varlistentry> + <term><option>--name</option></term><listitem><para>Имя существующего дескриптора облачной сети.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloud-network-info"> + <title>cloud network info</title> + <remark role="help-copy-synopsis"/> + <para> + Показывает информацию о дескрипторе облачной сети. + </para> + <variablelist> + <varlistentry> + <term><option>--name</option></term><listitem><para>Имя существующего дескриптора облачной сети.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsect1> + +</refentry> + diff --git a/doc/manual/ru_RU/man_VBoxManage-cloudimage.xml b/doc/manual/ru_RU/man_VBoxManage-cloudimage.xml new file mode 100644 index 00000000..82b10554 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-cloudimage.xml @@ -0,0 +1,242 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage cloud image +--> +<!-- + Copyright (C) 2018-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-cloudimage" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage cloud image</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-cloudimage</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-cloudimage</refname> + <refpurpose>Управление облачными образами</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-create" sepchar=" "> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <arg choice="plain">image</arg> + <arg choice="plain">create</arg> + <arg choice="req">--display-name=<replaceable>имя</replaceable></arg> + <arg>--bucket-name=<replaceable>имя</replaceable></arg> + <arg>--object-name=<replaceable>имя</replaceable></arg> + <arg>--instance-id=<replaceable>уникальный id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-info" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <arg choice="plain">image</arg> + <arg choice="plain">info</arg> + <arg choice="req">--id=<replaceable>уникальный id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-delete" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <arg choice="plain">image</arg> + <arg choice="plain">delete</arg> + <arg choice="req">--id=<replaceable>уникальный id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-import" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <arg choice="plain">image</arg> + <arg choice="plain">import</arg> + <arg choice="req">--id=<replaceable>уникальный id</replaceable></arg> + <arg>--bucket-name=<replaceable>имя</replaceable></arg> + <arg>--object-name=<replaceable>имя</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-export" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <arg choice="plain">image</arg> + <arg choice="plain">export</arg> + <arg choice="req">--id=<replaceable>уникальный id</replaceable></arg> + <arg choice="req">--display-name=<replaceable>имя</replaceable></arg> + <arg>--bucket-name=<replaceable>имя</replaceable></arg> + <arg>--object-name=<replaceable>имя</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + + <refsect2 id="vboxmanage-cloudimage-common-options"> + <title>Общие параметры</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>Подкоманды <command>cloudimage</command> реализуют стандартные операции над облачными образами, как то + create/delete/show/import/export. Следующие общие параметры должны находиться между "cloud" и последующими подкомандами:</para> + <variablelist> + <varlistentry> + <term>--provider=<replaceable>имя</replaceable></term> + <listitem><para>Короткое имя облачного провайдера.</para></listitem> + </varlistentry> + <varlistentry> + <term>--profile=<replaceable>имя</replaceable></term> + <listitem><para>Имя облачного профиля. </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-create"> + <title>cloud image create</title> + <remark role="help-copy-synopsis"/> + <para> + Создает новый образ в облаке. + Существует два стандартных способа создать образ в облаке: + 1. Создать образ из объекта в облачном хранилище; + 2. Создать образ из существующего облачного экземпляра. + Для первого способа требуются параметры: + bucket-name - имя облачной корзины где находится объект; + object-name - имя объекта в корзине; + display-name - имя для нового образа в облаке. + Для второго способа требуются параметры: + instance-id - Id экземпляра в облаке; + display-name - имя для нового образа в облаке. + </para> + <variablelist> + <varlistentry> + <term><option>--display-name</option></term><listitem><para>Имя для нового образа в облаке.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bucket-name</option></term><listitem><para>Имя облачной корзины где размещен объект.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--object-name</option></term><listitem><para>Имя объекта в корзине.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--instance-id</option></term><listitem><para>Уникальный идентификатор, полностью идентифицирующий экземпляр в облаке.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-info"> + <title>cloud image info</title> + <remark role="help-copy-synopsis"/> + <para> + Показывает информацию об облачном образе с указанным id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Уникальный идентификатор, полностью идентифицирующий образ в облаке.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-delete"> + <title>cloud image delete</title> + <remark role="help-copy-synopsis"/> + <para> + Удаляет образ с указанным id из облака. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Уникальный идентификатор, полностью идентифицирующий образ в облаке.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-import"> + <title>cloud image import</title> + <remark role="help-copy-synopsis"/> + <para> + Импортирует образ с указанным id из облака на локальный хост. + Результатом является объект в локальной папке "temp" локального хоста. + Возможный подход может состоят из двух основных этапов: + 1. Создать объект из образа в облачном хранилище; + 2. Загрузить объект на локальный хост. + Поэтому, следующие параметры могут потребоваться: + bucket-name - имя облачной корзины где будет создан объект; + object-name - имя объекта в корзине. Если параметр "object-name" отсутствует, будет использовано показанное имя образа. + Если первый этап не нужен, требуется только параметр "id". + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Уникальный идентификатор, полностью идентифицирующий образ в облаке.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bucket-name</option></term><listitem><para>Имя облачной корзины, где будет создан объект.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--object-name</option></term> + <listitem> + <para> + Имя созданного объекта в корзине. У загруженного объекта будет такое же имя. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-export"> + <title>cloud image export</title> + <remark role="help-copy-synopsis"/> + <para> + Экспортирует существующий образ VBox с указанным uuid из локального хоста в облако. + Результатом является новый образ в облаке. + Возможный подход может состоят из двух основных этапов: + 1. Загрузить образ VBox в облачное хранилище; + 2. Создать образ из загруженного объекта. + Поэтому, следующие параметры могут потребоваться: + bucket-name - имя облачной корзины куда будет загружен объект; + object-name - имя объекта в корзине. Если параметр "object-name" отсутствует, будет использован id образа; + display-name - имя для нового образа в облаке. + Если первый этап не нужен, требуются только параметры "id" и "display-name". + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Уникальный идентификатор образа в VirtualBox.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--display-name</option></term><listitem><para>Имя для нового образа в облаке.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bucket-name</option></term><listitem><para>Имя облачной корзины куда будет загружен образ (объект).</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--object-name</option></term><listitem><para>Имя объекта в корзине.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + +</refentry> + diff --git a/doc/manual/ru_RU/man_VBoxManage-cloudinstance.xml b/doc/manual/ru_RU/man_VBoxManage-cloudinstance.xml new file mode 100644 index 00000000..b2bcee26 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-cloudinstance.xml @@ -0,0 +1,228 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + manpage, user manual, usage: VBoxManage cloud instance +--> +<!-- + Copyright (C) 2018-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-cloudinstance" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage cloud instance</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-cloudinstance</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-cloudinstance</refname> + <refpurpose>Управление облачными экземплярами</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-create" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <arg choice="plain">instance</arg> + <arg choice="plain">create</arg> + <arg choice="req">--domain-name=<replaceable>имя</replaceable></arg> + <group choice="req"> + <arg choice="req">--image-id=<replaceable>id</replaceable></arg> + <arg choice="req">--boot-volume-id=<replaceable>id</replaceable></arg> + </group> + <arg choice="req">--display-name=<replaceable>имя</replaceable></arg> + <arg choice="req">--shape=<replaceable>тип</replaceable></arg> + <arg choice="req">--subnet=<replaceable>id</replaceable></arg> + <arg>--boot-disk-size=<replaceable>размер в ГБ</replaceable></arg> + <arg>--publicip=<replaceable>true/false</replaceable></arg> + <arg>--privateip=<replaceable>IP адрес</replaceable></arg> + <arg rep="repeat">--public-ssh-key=<replaceable>ключевая строка</replaceable></arg> + <arg>--launch-mode=<replaceable>NATIVE/EMULATED/PARAVIRTUALIZED</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-info" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <arg choice="plain">instance</arg> + <arg choice="plain">info</arg> + <arg choice="req">--id=<replaceable>уникальный id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-terminate" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <arg choice="plain">instance</arg> + <arg choice="plain">terminate</arg> + <arg choice="req">--id=<replaceable>уникальный id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-start" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <arg choice="plain">instance</arg> + <arg choice="plain">start</arg> + <arg choice="req">--id=<replaceable>уникальный id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-pause" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <arg choice="plain">instance</arg> + <arg choice="plain">pause</arg> + <arg choice="req">--id=<replaceable>уникальный id</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + + <refsect2 id="vboxmanage-cloudinstance-common-options"> + <title>Общие параметры</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>Подкоманды <command>cloudinstance</command> реализуют стандартные операции над облачными экземплярами, как то + start/pause/show/terminate. Следующие общие параметры должны быть помещены между "cloud" и последующими подкомандами:</para> + <variablelist> + <varlistentry> + <term>--provider=<replaceable>имя</replaceable></term> + <listitem><para>Короткое имя облачного провайдера.</para></listitem> + </varlistentry> + <varlistentry> + <term>--profile=<replaceable>имя</replaceable></term> + <listitem><para>Имя облачного профиля. </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-create"> + <title>cloud instance create</title> + <remark role="help-copy-synopsis"/> + <para> + Создает новый экземпляр в облаке. + Существует два стандартных способа создать экземпляр в облаке: + 1. Создать экземпляр из существующего пользовательского образа. + 2. Создать экземпляр из существующего загрузочного тома. Этот загрузочный том не должен быть подключен + к какому-либо экземпляру. + Для первого способа требуются параметры: image-id, boot-disk-size. + Для второго способа требуются параметры: boot-volume-id. + Остальные параметры являются общими для обоих способов: + display-name, launch-mode, subnet-id, publicIP, privateIP, shape, domain. + </para> + <variablelist> + <varlistentry> + <term><option>--domain-name</option></term><listitem><para>Облачный домен, где создается экземпляр.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--image-id</option></term><listitem><para>Уникальный идентификатор, полностью идентифицирующий пользовательский образ в облаке.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--boot-volume-id</option></term><listitem><para>Уникальный идентификатор, полностью идентифицирующий загрузочный том в облаке.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--display-name</option></term><listitem><para>Имя для нового экземпляра в облаке.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--shape</option></term><listitem><para>Форма экземпляра, определяющая количество ЦПУ и размер RAM памяти.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--subnet</option></term><listitem><para>Уникальный идентификатор, полностью идентифицирующий существующую подсеть в облаке для использования экземпляром.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--boot-disk-size</option></term><listitem><para>Размер загрузочного образа в ГБ. По умолчанию 50 ГБ.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--publicip</option></term><listitem><para>У экземпляра публичный IP или нет.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--privateip</option></term><listitem><para>Приватный IP адрес для созданного экземпляра.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--public-ssh-key</option></term> + <listitem> + <para>Публичный ключ SSH, используемый для подключения к экземпляру через + SSH. Этот параметр может быть указан несколько раз если нужно указать + несколько ключей, например: "--public-ssh-key=firstSSHKey --public-ssh-key=secondSSHKey". + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--launch-mode</option></term><listitem><para>Наиболее известные значения здесь могут быть EMULATED, NATIVE, PARAVIRTUALIZED.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-info"> + <title>cloud instance info</title> + <para> + Показывает информацию об облачном экземпляре с указанным id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Уникальный идентификатор, полностью идентифицирующий экземпляр в облаке.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-terminate"> + <title>cloud instance termination</title> + <para> + Удаляет облачный экземпляр с указанным id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Уникальный идентификатор, полностью идентифицирующий экземпляр в облаке.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-start"> + <title>cloud instance start</title> + <para> + Запускает облачный экземпляр с указанным id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Уникальный идентификатор, полностью идентифицирующий экземпляр в облаке.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-pause"> + <title>cloud instance pause</title> + <para> + Приостанавливает облачный экземпляр с указанным id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Уникальный идентификатор, полностью идентифицирующий экземпляр в облаке.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-cloudlist.xml b/doc/manual/ru_RU/man_VBoxManage-cloudlist.xml new file mode 100644 index 00000000..e3b28460 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-cloudlist.xml @@ -0,0 +1,145 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage cloud list +--> +<!-- + Copyright (C) 2018-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-cloudlist" lang="en"> + + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage cloud list</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-cloudlist</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-cloudlist</refname> + <refpurpose>Команда cloud list дает информацию о некоторых стандартных сущностях в каждом облаке + и которая может быть представлена списком, например, списки экземпляров, образов дисков, сетей, т.д.</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-cloudlist-instances"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <arg choice="plain">list</arg> + <arg choice="plain">instances</arg> + <arg>--state=<replaceable>строка</replaceable></arg> + <arg>--compartment-id=<replaceable>строка</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudlist-images"> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <arg choice="plain">list</arg> + <arg choice="plain">images</arg> + <arg choice="req">--compartment-id=<replaceable>строка</replaceable></arg> + <arg>--state=<replaceable>строка</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <refsect2 id="vboxmanage-cloud-common-options"> + <title>Общие параметры</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>Слово "cloud" объединяет все команды, связанные с взаимодействием с облаком. Следующие + общие параметры необходимо разместить между "cloud" и последующими подкомандами, в нашем случае "list":</para> + <variablelist> + <varlistentry> + <term>--provider=<replaceable>имя</replaceable></term> + <listitem><para>Короткое имя облачного провайдера.</para></listitem> + </varlistentry> + <varlistentry> + <term>--profile=<replaceable>имя</replaceable></term> + <listitem><para>Имя облачного профиля. </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudlist-instances"> + <title>cloud list instances</title> + <remark role="help-copy-synopsis"/> + <para> + Отображает список экземпляров указанной секции. + </para> + <variablelist> + <varlistentry> + <term>--state<replaceable>"running/paused/terminated"</replaceable></term> + <listitem> + <para>Состояние облачного экземпляра. На данный момент возможны следующие состояния: + "running/paused/terminated". Если состояние не указано, возвращается список экземпляров + со всеми возможными состояниями. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment-id</option></term> + <listitem> + <para>Секция - это логический контейнер, используемый для организации и изоляции + облачных ресурсов. У разных облачных провайдеров эта сущность называется по-разному. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudlist-images"> + <title>cloud list images</title> + <remark role="help-copy-synopsis"/> + <para> + Отображает список образов для указанной секции. + </para> + <variablelist> + <varlistentry> + <term>--state<replaceable>"available/disabled/deleted"</replaceable></term> + <listitem> + <para>Состояние облачного образа. На данный момент возможны следующие состояния: + "available/disabled/deleted". Если состояние не указано, возвращается список + образов со всеми возможными состояниями. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment-id</option></term> + <listitem> + <para>Секция - это логический контейнер, используемый для организации и изоляции + облачных ресурсов. У разных облачных провайдеров эта сущность называется по-разному. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> +</refentry> + diff --git a/doc/manual/ru_RU/man_VBoxManage-cloudprofile.xml b/doc/manual/ru_RU/man_VBoxManage-cloudprofile.xml new file mode 100644 index 00000000..b5349eea --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-cloudprofile.xml @@ -0,0 +1,191 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage cloudprofile +--> +<!-- + Copyright (C) 2018-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-cloudprofile" lang="en"> + + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage cloudprofile</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-cloudprofile</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-cloudprofile</refname> + <refpurpose>Управление облачными профилями</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-cloudprofile-add"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage cloudprofile</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <arg choice="plain">add</arg> + <arg>--clouduser=<replaceable>уникальный id</replaceable></arg> + <arg>--fingerprint=<replaceable>строка MD5</replaceable></arg> + <arg>--keyfile=<replaceable>путь</replaceable></arg> + <arg>--passphrase=<replaceable>строка</replaceable></arg> + <arg>--tenancy=<replaceable>уникальный id</replaceable></arg> + <arg>--compartment=<replaceable>уникальный id</replaceable></arg> + <arg>--region=<replaceable>строка</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudprofile-update"> + <command>VBoxManage cloudprofile</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <arg choice="plain">update</arg> + <arg>--clouduser=<replaceable>уникальный id</replaceable></arg> + <arg>--fingerprint=<replaceable>строка MD5</replaceable></arg> + <arg>--keyfile=<replaceable>путь</replaceable></arg> + <arg>--passphrase=<replaceable>строка</replaceable></arg> + <arg>--tenancy=<replaceable>уникальный id</replaceable></arg> + <arg>--compartment=<replaceable>уникальный id</replaceable></arg> + <arg>--region=<replaceable>строка</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudprofile-delete"> + <command>VBoxManage cloudprofile</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <arg choice="plain">delete</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudprofile-show"> + <command>VBoxManage cloudprofile</command> + <arg choice="req">--provider=<replaceable>имя</replaceable></arg> + <arg choice="req">--profile=<replaceable>имя</replaceable></arg> + <arg choice="plain">show</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + + <refsect2 id="vboxmanage-cloudprofile-common-options"> + <title>Общие параметры</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> Подкоманды <command>cloudprofile</command> реализуют стандартные CRUD операции над облачным профилем. + Следующие общие параметры должны быть помещены между "cloud" и последующими подкомандами:</para> + <variablelist> + <varlistentry> + <term>--provider=<replaceable>имя</replaceable></term> + <listitem><para>Короткое имя облачного провайдера.</para></listitem> + </varlistentry> + <varlistentry> + <term>--profile=<replaceable>имя</replaceable></term> + <listitem><para>Имя облачного профиля.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudprofile-add"> + <title>cloudprofile add</title> + <remark role="help-copy-synopsis"/> + <para> + Добавляет новый облачный профиль для указанного облачного провайдера. + </para> + <variablelist> + <varlistentry> + <term><option>--clouduser</option></term><listitem><para>Имя, полностью идентифицирующее пользователя у указанного облачного провайдера.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--fingerprint</option></term><listitem><para>Отпечаток используемой ключевой пары.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--keyfile</option></term><listitem><para>Полный путь и имя файла приватного ключа.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--passphrase</option></term><listitem><para>Парольная фраза используемая для ключа, если он зашифрован.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tenancy</option></term><listitem><para>ID вашей аренды.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment</option></term><listitem><para>ID вашей секции.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--region</option></term><listitem><para>Имя региона. Регион - это где вы планируете развертывать приложение.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudprofile-show"> + <title>cloudprofile show</title> + <remark role="help-copy-synopsis"/> + <para> + Показывает информацию об облачном профиле для указанного облачного провайдера. + </para> + </refsect2> + + <refsect2 id="vboxmanage-cloudprofile-update"> + <title>cloudprofile update</title> + <remark role="help-copy-synopsis"/> + <para> + Изменяет облачный профиль для указанного облачного провайдера. + </para> + <variablelist> + <varlistentry> + <term><option>--clouduser</option></term><listitem><para>Имя, полностью идентифицирующее пользователя у указанного облачного провайдера.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--fingerprint</option></term><listitem><para>Отпечаток используемой ключевой пары.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--keyfile</option></term><listitem><para>Полный путь и имя файла приватного ключа.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--passphrase</option></term><listitem><para>Парольная фраза используемая для ключа, если он зашифрован.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tenancy</option></term><listitem><para>ID вашей аренды.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment</option></term><listitem><para>ID вашей секции.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--region</option></term><listitem><para>Имя региона. Регион - это где вы планируете развертывать приложение.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudprofile-delete"> + <title>cloudprofile delete</title> + <remark role="help-copy-synopsis"/> + <para> + Удаляет облачный профиль для указанного облачного провайдера. + </para> + </refsect2> + + </refsect1> + +</refentry> + diff --git a/doc/manual/ru_RU/man_VBoxManage-common.xml b/doc/manual/ru_RU/man_VBoxManage-common.xml new file mode 100644 index 00000000..3c370208 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-common.xml @@ -0,0 +1,279 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-common" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage</refname> + <refpurpose>&product-name; интерфейс командной строки</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-common"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage</command> + <group> + <arg choice="plain">-V</arg> + <arg choice="plain">--version</arg> + </group> + <arg>--dump-build-type</arg> + <group> + <arg choice="plain">-q</arg> + <arg choice="plain">--nologo</arg> + </group> + <arg>--settingspw=<replaceable>пароль</replaceable></arg> + <arg>--settingspwfile=<replaceable>файл с паролем</replaceable></arg> + <arg>@<replaceable>файл ответов</replaceable></arg> + <arg><arg>help</arg> <replaceable>подкоманда</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage</command> - это интерфейс командной + строки (CLI) для ПО &product-name;. CLI поддерживает весь + функционал, доступный из графического интерфейса &product-name; + (GUI). В дополнении, можно использовать команду + <command>VBoxManage</command> для управления функционалом + ядра виртуализации, недоступного из GUI. + </para> + <para> + Каждый раз, когда вы вызываете команду <command>VBoxManage</command>, + исполняется только одна команда. Однако заметим, что некоторые + подкоманды <command>VBoxManage</command> вызывают несколько + подкоманд. + </para> + <para> + Запустите команду <command>VBoxManage</command> из командной строки + операционной системы (ОС) хоста для управления ПО &product-name;. + </para> + <para> + Команда <command>VBoxManage</command> находится в следующих местах + в зависимости от операционной системы хоста: + </para> + <itemizedlist> + <listitem><para> + <emphasis role="bold">Linux:</emphasis> + <filename>/usr/bin/VBoxManage</filename> + </para></listitem> + <listitem><para> + <emphasis role="bold">Mac OS X:</emphasis> + <filename>/Applications/VirtualBox.app/Contents/MacOS/VBoxManage</filename> + </para></listitem> + <listitem><para> + <emphasis role="bold">Oracle Solaris:</emphasis> + <filename>/opt/VirtualBox/bin/VBoxManage</filename> + </para></listitem> + <listitem><para> + <emphasis role="bold">Windows:</emphasis> + <filename>C:\Program + Files\Oracle\VirtualBox\VBoxManage.exe</filename> + </para></listitem> + </itemizedlist> + <para> + В дополнении к управлению виртуальными машинами (ВМ) через CLI или + GUI, можно использовать <command>VBoxHeadless</command> CLI для + управления ВМ напрямую. + </para> + <para> + Команда <command>VBoxManage</command> производит специфические + задачи через подкоманды, такие как <command>list</command>, + <command>createvm</command> и <command>startvm</command>. Смотри + соответствующую информацию по каждой подкоманде + <command>VBoxManage</command>. + </para> + <para> + Если нужно, ВМ может быть указана по ее имени или универсальному + уникальному идентификатору (UUID). + </para> + <para> + Команда <command>VBoxManage list vms</command> может быть + использована для получения информации обо всех зарегистрированных + на данный момент ВМ, включая их имена и UUID. + </para> + <para> + Заметим, что имя ВМ должно быть заключено в кавычки если оно содержит + пробелы. + </para> + <refsect2 id="vboxmanage-common-options"> + <title>Общие настройки</title> + <variablelist> + <varlistentry> + <term><option>--nologo</option></term> + <listitem><para> + Подавляет вывод логотипа. Опция полезна для скриптов. + </para><para> + Краткая версия этой опции: <option>-q</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--settingspw=[<replaceable>пароль</replaceable>]</option></term> + <listitem><para> + Указывает пароль для доступа к настройкам. Опционально, можно + указать сам пароль в качестве аргумента к опции. Если этого + не будет сделано, команда <command>VBoxManage</command> + спросит пароль у вас. + </para><para> + Пароль для доступа к настройкам - это функция безопасности, + которая шифрует настройки. По умолчанию настройки сохраняются + обычным текстом в открытом виде. + </para><para> + Вы не можете расшифровать зашифрованные настройки. Так что, + если настройки зашифрованы, вы должны продолжать указывать + <option>--settingspw</option> или + <option>--settingspwfile</option>. + </para><para> + В настоящее время шифруется только пароль iSCSI. + </para><remark> + Данный дизайн не укладывается в Рекомендации по безопасности + Oracle. Вы не должны указывать пароль в командной строке как + аргумент, так как он может отображаться в списке процессов. + </remark></listitem> + </varlistentry> + <varlistentry> + <term><option>--settingspwfile=<replaceable>файл с паролем</replaceable></option></term> + <listitem><para> + Указывает файл, содержащий пароль к настройкам. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--version</option></term> + <listitem><para> + Показывает информацию о версии команды + <command>VBoxManage</command>. + </para><para> + Краткая версия это опции: <option>-V</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term>@<replaceable>файл ответов</replaceable></term> + <listitem><para> + Загружает аргументы из файла ответов в формате + Bourne shell. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>подкоманда</replaceable></term> + <listitem><para> + Указывает одну из подкоманд <command>VBoxManage</command>, + такие как <command>controlvm</command>, + <command>createvm</command>, <command>list</command>, + <command>modifyvm</command>, + <command>showvminfo</command>, <command>startvm</command>, + <command>storageattach</command> и + <command>storagectl</command>. + </para><para> + Каждая подкоманда описывается в своем топике, некоторые + из них показаны в секции 'Смотрите также'. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + Следующая команда создает виртуальную машину с именем + <literal>Win8</literal> и регистрирует ее в &product-name;, + используя опцию <option>--register</option>. + </para> +<screen>$ VBoxManage createvm --name "Win8" --register +Виртуальная машина 'Win8' создана и зарегистрирована. +UUID: <replaceable>строка UUID</replaceable> +Файл настроек: '/home/<replaceable>имя пользователя</replaceable>/VirtualBox VMs/Win8/Win8.vbox'</screen> + <para> + Вывод команды показывает, что ВМ <literal>Win8</literal> + назначен UUID и XML файл настроек машины. + </para> + <para> + Вы можете использовать команду <command>VBoxManage showvminfo</command> + для просмотра информации о конфигурации ВМ. + </para> + <para> + Следующий пример использует команду <command>VBoxManage + modifyvm</command> для изменения размера памяти у ВМ + <literal>Windows XP</literal> VM до 1024 мегабайта: + </para> +<screen>$ VBoxManage modifyvm "Windows XP" --memory 1024</screen> + <para> + Заметим, что вы можете использовать команду <command>VBoxManage modifyvm</command> + даже если ВМ выключена. + </para> + <para> + Вы можете использовать команду <command>VBoxManage storagectl</command> + или команду <command>VBoxManage storageattach</command> для + изменения конфигурации носителей у ВМ. Например, чтобы создать + SATA контроллер с именем <literal>sata01</literal> и добавить + его в ВМ <literal>ol7</literal> VM используйте: + </para> +<screen>$ VBoxManage storagectl ol7 --name "sata01" --add sata</screen> + <para> + Используйте команду <command>VBoxManage startvm</command> для старта + ВМ, которая сейчас выключена. Например, чтобы запустить ВМ + <literal>win7</literal> укажите: + </para> +<screen>$ VBoxManage startvm win7</screen> + <para> + Используйте команду <command>VBoxManage controlvm</command> + для приостановки или сохранения состояния ВМ, которая сейчас работает. + Вы также можете использовать эту команду для изменения настроек + ВМ. Например, чтобы включить аудио вход для ВМ <literal>ol6u9</literal> + используйте: + </para> +<screen>$ VBoxManage controlvm ol6u9 audioin on</screen> + </refsect1> + + <refsect1> + <title>Смотрите также</title> + <para> + <xref linkend="vboxmanage-controlvm" />, + <xref linkend="vboxmanage-createvm" />, + <xref linkend="vboxmanage-list" />, + <xref linkend="vboxmanage-modifyvm" />, + <xref linkend="vboxmanage-showvminfo" />, + <xref linkend="vboxmanage-startvm" />, + <xref linkend="vboxmanage-storageattach" />, + <xref linkend="vboxmanage-storagectl" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-controlvm.xml b/doc/manual/ru_RU/man_VBoxManage-controlvm.xml new file mode 100644 index 00000000..0b990052 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-controlvm.xml @@ -0,0 +1,2174 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage controlvm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-controlvm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage controlvm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-controlvm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-controlvm</refname> + <refpurpose>изменение состояния и настроек работающей виртуальной машины</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-controlvm-pause"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">pause</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-resume"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">resume</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-reset"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">reset</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-poweroff"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">poweroff</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-savestate"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">savestate</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-acpipowerbutton"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">acpipowerbutton</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-acpisleepbutton"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">acpisleepbutton</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-reboot"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">reboot</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-shutdown"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">shutdown</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-keyboardputscancode"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">keyboardputscancode</arg> + <arg choice="req"><replaceable>hex</replaceable></arg> + <arg rep="repeat"><replaceable>hex</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-keyboardputstring"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">keyboardputstring</arg> + <arg choice="req"><replaceable>строка</replaceable></arg> + <arg rep="repeat"><replaceable>строка</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-keyboardputfile"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">keyboardputfile</arg> + <arg choice="req"><replaceable>имя-файла</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-setlinkstate"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">setlinkstate<replaceable>N</replaceable></arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-nic"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">nic<replaceable>N</replaceable></arg> + <group choice="req"> + <arg choice="plain">null</arg> + <arg choice="plain">nat</arg> + <arg choice="plain">bridged</arg> + <arg choice="plain">intnet</arg> + <arg choice="plain">hostonly</arg> + <arg choice="plain">generic</arg> + <arg choice="plain">natnetwork</arg> + </group> + <arg><replaceable>имя-устройства</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-nictrace"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">nictrace<replaceable>N</replaceable></arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-nictracefile"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">nictracefile<replaceable>N</replaceable></arg> + <arg choice="req"><replaceable>имя-файла</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-nicproperty"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">nicproperty<replaceable>N</replaceable></arg> + <arg choice="req"><replaceable>имя-свойства</replaceable>=<replaceable>значение-свойства</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-nicpromisc"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">nicpromisc<replaceable>N</replaceable></arg> + <group choice="req"> + <arg choice="plain">deny</arg> + <arg choice="plain">allow-vms</arg> + <arg choice="plain">allow-all</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-natpf"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">natpf<replaceable>N</replaceable></arg> + <group choice="req"> + <arg choice="plain">[<replaceable>имя-правила</replaceable>]<arg choice="plain">,tcp</arg></arg> + <arg choice="plain">udp,<arg><replaceable>IP-хоста</replaceable></arg>, + <arg choice="plain"><replaceable>порт-хоста</replaceable>,</arg> + <arg><replaceable>IP-гостя</replaceable></arg>, + <arg choice="plain"><replaceable>порт-гостя</replaceable></arg></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-natpf-delete"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">natpf<replaceable>N</replaceable> delete</arg> + + <arg choice="req"><replaceable>имя-правила</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-guestmemoryballoon"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">guestmemoryballoon</arg> + <arg choice="req"><replaceable>размер-balloon-памяти</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-usbattach"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">usbattach</arg> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>адрес</replaceable></arg> + </group> + <arg>--capturefile=<replaceable>имя-файла</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-usbdetach"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">usbdetach</arg> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>адрес</replaceable></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-audioin"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">audioin</arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-audioout"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">audioout</arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-clipboard-mode"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">clipboard mode</arg> + <group choice="req"> + <arg choice="plain">disabled</arg> + <arg choice="plain">hosttoguest</arg> + <arg choice="plain">guesttohost</arg> + <arg choice="plain">bidirectional</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-draganddrop"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">draganddrop</arg> + <group choice="req"> + <arg choice="plain">disabled</arg> + <arg choice="plain">hosttoguest</arg> + <arg choice="plain">guesttohost</arg> + <arg choice="plain">bidirectional</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-vrde"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">vrde</arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-vrdeport"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">vrdeport</arg> + <arg choice="req"><replaceable>port</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-vrdeproperty"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">vrdeproperty</arg> + <arg choice="req"><replaceable>имя-свойства</replaceable>=<replaceable>значение-свойства</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-vrdevideochannelquality"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">vrdevideochannelquality</arg> + <arg choice="req"><replaceable>процент</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-setvideomodehint"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">setvideomodehint</arg> + <arg choice="req"><replaceable>разрешение-x</replaceable></arg> + <arg choice="req"><replaceable>разрешение-y</replaceable></arg> + <arg choice="req"><replaceable>бит/пиксел</replaceable></arg> + <arg><arg><replaceable>дисплей</replaceable></arg><group> + <arg choice="plain">enabled:yes | no</arg> + <arg><replaceable>начальная-точка-x</replaceable> <replaceable>начальная-точка-y</replaceable></arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-setscreenlayout"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">setscreenlayout</arg> + <arg choice="req"><replaceable>экран</replaceable></arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">primary <replaceable>начальная-точка-x</replaceable> <replaceable>начальная-точка-y</replaceable> <replaceable>разрешение-x</replaceable> <replaceable>разрешение-y</replaceable> <replaceable>бит/пиксел</replaceable></arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-screenshotpng"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">screenshotpng</arg> + <arg choice="req"><replaceable>имя-файла</replaceable></arg> + <arg><replaceable>display</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">recording</arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-screens"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">recording screens</arg> + <group choice="req"> + <arg choice="plain">all</arg> + <arg choice="plain">none</arg> + <arg choice="plain"><replaceable>экран</replaceable>,[<replaceable>экран</replaceable>...]</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-filename"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">recording filename</arg> + <arg choice="req">filename</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-videores"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">recording videores</arg> + <arg choice="req"><replaceable>ширина</replaceable>x<replaceable>высота</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-videorate"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">recording videorate</arg> + <arg choice="req"><replaceable>битрейт</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-videofps"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">recording videofps</arg> + <arg choice="req"><replaceable>кадров/сек</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-maxtime"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">recording maxtime</arg> + <arg choice="req"><replaceable>сек</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-maxfilesize"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">recording maxfilesize</arg> + <arg choice="req"><replaceable>МБ</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-setcredentials"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">setcredentials</arg> + <arg choice="req"><replaceable>имя-пользователя</replaceable></arg> + <arg choice="plain">--passwordfile=<group choice="req"> + <arg choice="plain"><replaceable>имя-файла</replaceable></arg> + <arg choice="plain"><replaceable>пароль</replaceable></arg> + </group></arg> + <arg choice="req"><replaceable>имя-домена</replaceable></arg> + <arg choice="plain">--allowlocallogon=<group choice="req"> + <arg choice="plain">yes</arg> + <arg choice="plain">no</arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-teleport"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">teleport</arg> + <arg choice="req">--host=<replaceable>имя-хоста</replaceable></arg> + <arg choice="req">--port=<replaceable>имя-порта</replaceable></arg> + <arg>--maxdowntime=<replaceable>мсек</replaceable></arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>имя-файла</replaceable></arg> + <arg choice="plain">--password=<replaceable>пароль</replaceable></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-plugcpu"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">plugcpu</arg> + <arg choice="req"><replaceable>ID</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-unplugcpu"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">unplugcpu</arg> + <arg choice="req"><replaceable>ID</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-cpuexecutioncap"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">cpuexecutioncap</arg> + <arg choice="req"><replaceable>число</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-vm-process-priority"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">vm-process-priority</arg> + <group choice="req"> + <arg choice="plain">default</arg> + <arg choice="plain">flat</arg> + <arg choice="plain">low</arg> + <arg choice="plain">normal</arg> + <arg choice="plain">high</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-webcam-attach"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">webcam attach</arg> + <arg><replaceable>путь</replaceable><arg><replaceable>настройки</replaceable></arg></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-webcam-detach"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">webcam detach</arg> + <arg><replaceable>путь</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-webcam-list"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">webcam list</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-addencpassword"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">addencpassword</arg> + <arg choice="req"><replaceable>ID</replaceable></arg> + <group choice="req"> + <arg choice="plain"><replaceable>файл-с-паролем</replaceable></arg> + <arg choice="plain">-</arg> + </group> + <arg>--removeonsuspend=<group choice="plain"> + <arg choice="plain">yes</arg> + <arg choice="plain">no</arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-removeencpassword"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">removeencpassword</arg> + <arg choice="req"><replaceable>ID</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-removeallencpasswords"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">removeallencpasswords</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-changeuartmode"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">changeuartmode<replaceable>N</replaceable></arg> + <group choice="plain"> + <arg choice="plain">disconnected</arg> + <arg choice="plain">server <replaceable>имя-канала</replaceable></arg> + <arg choice="plain">client <replaceable>имя-канала</replaceable></arg> + <arg choice="plain">tcpserver <replaceable>порт</replaceable></arg> + <arg choice="plain">tcpclient <replaceable>имя-хоста</replaceable>:<replaceable>порт</replaceable></arg> + <arg choice="plain">file <replaceable>имя-файла</replaceable></arg> + <arg choice="plain"><replaceable>имя-устройства</replaceable></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-autostart-enabled"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">autostart-enabled<replaceable>N</replaceable></arg> + <group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-autostart-delay"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">autostart-delay<replaceable>секунд</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage controlvm</command> позволяет изменить + состояние работающей виртуальной машины (ВМ). Следующие секции + описывают подкоманды, которые можно использовать: + </para> + <refsect2 id="vboxmanage-controlvm-pause"> + <title>Приостановить виртуальную машину</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> pause</command> временно + приостанавливает выполнение ВМ. Когда ВМ приостановлена, ее + состояние не изменяется постоянно. + </para> + <para> + Окно ВМ становится серым и заголовок окна показывает, что ВМ + приостановлена на текущий момент. Это действие эквивалентно + выбору <emphasis role="bold">Приостановить</emphasis> из + меню <emphasis role="bold">Машина</emphasis> графического + интерфейса. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-resume"> + <title>Возобновить выполнение приостановленной виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> resume</command> перезапускает + выполнение приостановленной ВМ. Это действие эквивалентно выбору + <emphasis role="bold">Возобновить</emphasis> из меню + <emphasis role="bold">Машина</emphasis> графического интерфейса. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-reset"> + <title>Сбросить виртуальную машину</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> reset</command> производит + холодный сброс ВМ. У этой команды тот же эффект, как и нажатие + кнопки "сброс" у физического компьютера. + </para> + <para> + Холодная перезагрузка немедленно перезапускает и перезагружает + гостевую операционную системы (ОС). Состояние ВМ перед сбросом + не сохраняется, поэтому можно потерять данные. Это действие + эквивалентно выбору <emphasis role="bold">Сброс</emphasis> из + меню <emphasis role="bold">Машина</emphasis> графического + интерфейса. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-poweroff"> + <title>Выключить виртуальную машину</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> poweroff</command> выключает + ВМ. У этой команды тот же эффект как и вытаскивание кабеля питания + из физического компьютера. + </para> + <para> + Состояние ВМ перед выключением не сохраняется, поэтому можно + потерять данные. Это действие эквивалентно выбору + <emphasis role="bold">Закрыть</emphasis> из меню + <emphasis role="bold">Машина</emphasis> графического интерфейса + или нажатию на кнопку "Закрыть" окна ВМ и затем выбору + <emphasis role="bold">Выключить машину</emphasis>. + </para> + <para> + Когда ВМ в состоянии "выключено", ее можно перезапустить. + Смотрите <xref linkend="vboxmanage-startvm" />. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-savestate"> + <title>Сохранить состояние виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> savestate</command> сохраняет + текущее состояние ВМ на диск и затем останавливает ВМ. + </para> + <para> + Действие эквивалентно выбору <emphasis role="bold">Закрыть</emphasis> + из меню <emphasis role="bold">Машина</emphasis> графического интерфейса + или нажатию на кнопку "Закрыть" окна ВМ и затем выбору + <emphasis role="bold">Сохранить состояние машины</emphasis>. + </para> + <para> + Когда ВМ в состоянии "выключено", ее можно перезапустить. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-acpipowerbutton"> + <title>Отправить ACPI сигнал выключения в виртуальную машину</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> acpipowerbutton</command> отправляет + ACPI сигнал выключения в ВМ. У этой команды тот же эффект как + и нажатие кнопки "Включить" на физическом компьютере. + </para> + <para> + Пока в ВМ работает гостевая ОС, обеспечивающая поддержку ACPI, + эта команда запускает правильный механизм остановки внутри ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-acpisleepbutton"> + <title>Отправить ACPI сигнал перехода в спящий режим в виртуальную машину</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> acpisleepbutton</command> отправляет + ACPI сигнал перехода в спящий режим в ВМ. + </para> + <para> + Пока в ВМ работает гостевая ОС, обеспечивающая поддержку ACPI, + эта команда запускает правильный механизм перехода в спящий + режим внутри ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-reboot"> + <title>Перезагрузить гостевую ОС</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> reboot</command> просит + гостевую ОС перезагрузиться. + </para> + <para> + Эта команда работает только если установлена + последняя версия Дополнений Гостевой ОС. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-shutdown"> + <title>Выключить гостевую ОС</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> shutdown</command> + просит гостевую ОС выключиться + </para> + <para> + Эта команда работает только если установлена + последняя версия Дополнений Гостевой ОС. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-keyboardputscancode"> + <title>Отправить клавиатурные сканкоды в виртуальную машину</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> keyboardputscancode</command> + отправляет команды клавиатурных сканкодов в ВМ. + </para> + <para> + По информации о клавиатурных сканкодах смотрите + <ulink url="http://www.win.tue.nl/~aeb/linux/kbd/scancodes-1.html" />. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-keyboardputstring"> + <title>Отправить клавиатурные строки в виртуальную машину</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> keyboardputstring</command> + отправляет клавиатурные строки в ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-keyboardputfile"> + <title>Отправить файл в виртуальную машину</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> keyboardputfile</command> + отправляет файл в ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-teleport"> + <title>Настроить цель для портирования виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> teleport</command> инициирует + операцию портирования между указанной ВМ и указанной системой + хоста. Смотрите <xref linkend="teleporting" />. + </para> + <para> + Если вы указываете пароль, он должен соответствовать паролю, + используемому при вызове команды <command>VBoxManage + modifyvm</command> для целевой машины. + </para> + <variablelist> + <varlistentry> + <term><option>--host=<replaceable>имя-хоста</replaceable></option></term> + <listitem><para> + Указывает имя ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--port=<replaceable>порт</replaceable></option></term> + <listitem><para> + Указывает порт, который ВМ должна прослушивать для получения + запросов на портирование с других ВМ. Номер порта может быть + любой свободный TCP/IP порт, например <literal>6000</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--maxdowntime=<replaceable>мсек</replaceable></option></term> + <listitem><para> + Задает максимальное время простоя в миллисекундах для портируемой + целевой виртуальной машины. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password=<replaceable>пароль</replaceable></option></term> + <listitem><para> + Указывает пароль, используемый исходной машиной для запроса + на портирование. Запрос удовлетворяется только если + исходная машины указывает тот же самый пароль. + </para><remark> + Такой дизайн не соответствует рекомендациям Oracle по безопасности. + Вы не должны указывать пароль в командной строке, потому что + его можно увидеть в списке процессов. + </remark><para> + Опция <option>--password</option> является взаимоисключающей с опцией + <option>--passwordfile</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--passwordfile=<replaceable>имя-файла</replaceable></option></term> + <listitem><para> + Указывает файл откуда берется пароль, испольуемый исходной + машиной для запроса на портирование. Запрос удовлетворяется + только если исходная машина указывает тот же самый пароль. + </para><para> + Если указатть в качестве имени файла <literal>stdin</literal>, + можно читать пароль со стандартного потока ввода. + </para><para> + Опция <option>--passwordfile</option> является взаимоисключающей + с опцией <option>--password</option>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-setlinkstate"> + <title>Установить состояние сетевого подключения для виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm <replaceable>имя-ВМ</replaceable> + setlinkstate<replaceable>N</replaceable></command> позволяет подключить + или отключить виртуальный сетевой кабель от экземпляра сетевого + интерфейса(<replaceable>N</replaceable>). Допустимые значения: + <literal>on</literal> и <literal>off</literal>. Значение по умолчанию + <literal>on</literal>. + </para> + <para> + Перед подключением виртуального сетевого кабеля используйте команду + <command>VBoxManage controlvm nictracefile<replaceable>N</replaceable> + </command> во время работы ВМ для задания имени файла для записи + журнала. Или используйте команду <command>VBoxManage modifyvm + --nic-trace-file<replaceable>N</replaceable>=<replaceable>имя-файла</replaceable></command> + для этих же целей, если ВМ не работает. + </para> + <para> + Эта подкоманда не влияет прямо на состояние работы ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-nic"> + <title>Задать тип сети, используемой виртуальной машиной</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm <replaceable>имя-ВМ</replaceable> + nic<replaceable>N</replaceable></command> указывает тип сети + в указаной сетевой карте ВМ. + Нумерация <replaceable>N</replaceable> начинается с + <literal>1</literal>. + </para> + <para> + Следующие допустимые типы сети также описаны в + <xref linkend="networkingmodes" />: + </para> + <itemizedlist> + <listitem><para> + <literal>null</literal> указывает, что ВМ не подключена к + хост-системе. + </para></listitem> + <listitem><para> + <literal>nat</literal> указывает, что ВМ использует сетевое + преобразование адресов (NAT). + </para></listitem> + <listitem><para> + <literal>bridged</literal> указывает, что ВМ использует + сетевой мост. + </para></listitem> + <listitem><para> + <literal>intnet</literal> указывает, что ВМ обменивается + с другими ВМ, используя внутреннюю сеть. + </para></listitem> + <listitem><para> + <literal>hostonly</literal> указывает, что ВМ использует + сеть хоста. + </para></listitem> + <listitem><para> + <literal>natnetwork</literal> указывает, что ВМ испльзует + сеть NAT. + </para></listitem> + <listitem><para> + <literal>generic</literal> указывает, что у ВМ есть доступ + у редко используемым под-режимами. + </para></listitem> + </itemizedlist> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-nictrace"> + <title>Отследить сетевой траффик виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm <replaceable>имя-ВМ</replaceable> + nictrace<replaceable>N</replaceable></command> позволяет + отслеживать сетевой траффик на указанной виртуальной сетевой + карте (<replaceable>N</replaceable>). + Нумерация <replaceable>N</replaceable> начинается с + <literal>1</literal>. Допустимые значения: <literal>on</literal> и + <literal>off</literal>. Значение по умолчанию + <literal>off</literal>. + </para> + <para> + Когда устанавливается в <literal>on</literal>, необходимо + использовать то же самое значение <replaceable>N</replaceable> + для команды <command>VBoxManage controlvm <replaceable>имя-ВМ</replaceable> + nictracefile<replaceable>N</replaceable></command>, что было + использовано для указания пути и имени файла журнала, в который + производится запись результатов отслеживания. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-nictracefile"> + <title>Задать файл журнала для отслеживания сетевого траффика виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm <replaceable>имя-ВМ</replaceable> + nictracefile<replaceable>N</replaceable></command> позволяет вам + задать имя файла журнала для отслеживания сетевого траффика для + указанной виртуальной сетевой карты (<replaceable>N</replaceable>). + Нумерация <replaceable>N</replaceable> начинается с + <literal>1</literal>. Убедитесь, что задано то же значение + <replaceable>N</replaceable>, какое использовано для команд + <command>VBoxManage controlvm <replaceable>имя-ВМ</replaceable> + nic<replaceable>N</replaceable></command> и + <command>VBoxManage controlvm <replaceable>имя-ВМ</replaceable> + nictrace<replaceable>N</replaceable></command>. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-nicpromisc"> + <title>Указать используемый неразборчивый режим для виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm <replaceable>имя-ВМ</replaceable> + nicpromisc<replaceable>N</replaceable></command> позволяет указать + как обрабатывать неразборчивый режим для сетевого моста. Значение + по умолчанию <literal>deny</literal> скрывает весь траффик, не + предназначенный для этой ВМ. Значение <literal>allow-vms</literal> + скрывает весь траффик хоста от этой ВМ, но позволяет ВМ просматривать + траффик с других ВМ. Значение <literal>allow-all</literal> убирает + это ограничение полностью. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-nicproperty"> + <title>Задать значение свойства сетевого бэкенда виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm <replaceable>имя-ВМ</replaceable> + nicproperty<replaceable>N</replaceable> + <replaceable>имя-свойства</replaceable>=<replaceable>значение-свойства</replaceable></command> + в комбинации с <literal>nicgenericdrv</literal> позволяет передать + значения свойств в редко используемые сетевые бэкенды. + </para> + <para> + Эти свойства специфичны для бэкенда и различны между драйверами + UDP туннеля и VDE бэкенда. Смотрите <xref linkend="network_udp_tunnel" />. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-natpf"> + <title>Задать правило для перенаправления портов NAT для виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm <replaceable>имя-ВМ</replaceable> + natpf<replaceable>N</replaceable></command> задает правило перенаправления + портов NAT. Смотрите <xref linkend="natforward"/>. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-natpf-delete"> + <title>Удалить правило для перенаправления портов NAT для виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда<command>VBoxManage controlvm <replaceable>имя-ВМ</replaceable> + natpf<replaceable>N</replaceable> delete</command> удаляет указанное + правило перенаправления портов NAT. Смотрите <xref linkend="natforward"/>. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-guestmemoryballoon"> + <title>Изменить размер гостевого memory balloon виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> guestmemoryballoon</command> + изменяет размер гостевого memory balloon. Гостевой memory balloon - + это память выделенная Дополнениями Гостевой ОС &product-name; у + гостевой системы и возвращенная гипервизору для использования + другими ВМ. Значение указывается в мегабайтах. Смотрите + <xref linkend="guestadd-balloon" />. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-usbattach"> + <title>Сделать USB устройство хост-системы видимым для виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> usbattach</command> динамически + подключает USB устройство хоста к ВМ, что делает его видимым. + Не нужно создавать фильтр. + </para> + <para> + Можно указывать USB устройство через Универсальный Уникальный + Идентификатор (UUID) или через адрес в хост-системе. используйте + команду <command>VBoxManage list usbhost</command> для получения + информации об USB устройствах хост-системы. + </para> + <para> + Используйте опцию <option>--capturefile</option> для задания + абсолютного пути к файлу для записи данных журналирования. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-usbdetach"> + <title>Сделать USB устройство хост-системы невидимым для виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> usbdetach</command> динамически + отключает USB устройство хоста от ВМ, что делает его невидимым. + Не нужно создавать фильтр. + </para> + <para> + Можно указывать USB устройство через Универсальный Уникальный + Идентификатор (UUID) или через адрес в хост-системе. используйте + команду <command>VBoxManage list usbhost</command> для получения + информации об USB устройствах хост-системы. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-audioin"> + <title>Включить или выключить аудио захват из хост-системы</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> audioin</command> указывает + включить или выключить аудио захват из хост-системы. Допустимые + значения: <literal>on</literal>, которая включает аудио захват и + <literal>off</literal>, которая выключает аудио захват. Значение + по умолчанию <literal>off</literal>. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-audioout"> + <title>Включить или выключить аудио воспроизведение из виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> audioout</command> указывает + включить или выключить аудио воспроизведение из гостевой ВМ. + Допустимые значения: <literal>on</literal>, которая включает + аудио воспроизведение и <literal>off</literal>, которая выключает + аудио воспроизведение. Значение по умолчанию <literal>off</literal>. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-clipboard-mode"> + <title>Задать как предоставить общий доступ к буферам обмена хост ОС или гостевой ОС</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> clipboard mode</command> задает + как предоставить общий доступ к буферам обмена гостевой системы + или хоста хост-системе или ВМ. Допустимые значения: + <literal>disabled</literal>, <literal>hosttoguest</literal>, + <literal>guesttohost</literal> и <literal>bidirectional</literal>. + Значение по умолчанию <literal>disabled</literal>. Смотрите + <xref linkend="generalsettings" />. + </para> + <para> + Этот функционал требует наличия Дополнений Гостевой ОС &product-name;, + установленных в ВМ. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-draganddrop"> + <title>Задать режим Drag and Drop между хост-системой и виртуальной машиной</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> draganddrop</command> Задает + текущий режим drag and drop, используемый между хост-системой + и ВМ. Допустимые значения: <literal>disabled</literal>, + <literal>hosttoguest</literal>, <literal>guesttohost</literal> + и <literal>bidirectional</literal>. Значение по умолчанию + <literal>disabled</literal>. Смотрите <xref linkend="guestadd-dnd" />. + </para> + <para> + Этот функционал требует наличия Дополнений Гостевой ОС &product-name;, + установленных в ВМ. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-vrde"> + <title>Включить или выключить VRDE сервер</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> vrde</command> включает или + выключает сервер Расширения Удаленного Рабочего Стола VirtualBox (VRDE), + если он установлен. Допустимые значения: <literal>on</literal> и + <literal>off</literal>. Значение по умолчанию <literal>off</literal>. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-vrdeport"> + <title>Задать порты VRDE сервера</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> vrdeport</command> задает + порт или диапазон портов к которым VRDE сервер может подключиться. + Значение по умолчанию <literal>default</literal> или + <literal>0</literal>, который обозначает стандартный RDP порт + <literal>3389</literal>. + </para> + <para> + Также смотрите описание опции <option>--vrde-port</option> в + <xref linkend="vboxmanage-modifyvm" />. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-vrdeproperty"> + <title>Задать номера портов и IP адреса VRDE сервера</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> vrdeproperty</command> указывает + номера портов и IP адрес в ВМ, к которым может подключиться VRDE + сервер. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + <itemizedlist> + <listitem><para> + <literal>TCP/Ports</literal> задает порт или диапазон портов + на которые может подключиться VRDE сервер. Значение по + умолчанию <literal>default</literal> или <literal>0</literal>, + который означает стандартный RDP порт <literal>3389</literal>. + </para><para> + Также смотрите описание опции <option>--vrde-port</option> в + <xref linkend="vboxmanage-modifyvm" />. + </para></listitem> + <listitem><para> + <literal>TCP/Address</literal> указывает IP адрес сетевого + интерфейса хоста, к которому может подключиться VRDE сервер. + Если указан, сервер принимает подключения только к указанному + сетевому интерфейсу хоста. + </para><para> + Также смотрите описание опции <option>--vrde-address</option> в + <xref linkend="vboxmanage-modifyvm" />. + </para></listitem> + <listitem><para> + <literal>VideoChannel/Enabled</literal> позволяет подключить + видеоканал Протокола Удаленного Рабочего Стола (VRDP). + Допустимые значения <literal>1</literal> для включения + видеоканала и <literal>0</literal> для выключения. Значение + по умолчанию <literal>0</literal>. Смотрите + <xref linkend="vrde-videochannel" />. + </para></listitem> + <listitem><para> + <literal>VideoChannel/Quality</literal> указывает уровень + сжатия JPEG в видеоканале сервера VRDE. Допустимые значения + между 10% и 100% включительно. Меньшие значения подразумевают + худшее качество, но более высокое сжатие. Значение по умолчанию + <literal>100</literal>. Смотрите <xref linkend="vrde-videochannel" />. + </para></listitem> + <listitem><para> + <literal>VideoChannel/DownscaleProtection</literal> позволяет + подключить функцию защиты от уменьшения масштаба видеоканала. + Укажите <literal>1</literal> для включения. По умолчанию + выключено. + </para><para> + Когда функция включена, если размер видео равен размеру теневого + буфера, видео отображается в полноэкранном режиме. Если размер + видео между полным экраном и порогом уменьшения масштаба, видео + не отображается, так как это может быть окно приложения, которое + может быть нечитаемым в случае уменьшения масштаба. Когда функция + отключена, функция защиты от уменьшения масштаба всегда пытается + отобразить видео. + </para></listitem> + <listitem><para> + <literal>Client/DisableDisplay</literal> позволяет отключить функцию + отображения сервера VRDE. Допустимые значения <literal>1</literal>, + отключающее функцию и null (<literal>""</literal>), + включающую эту функцию. Значение по умолчанию null. Смотрите + <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>Client/DisableInput</literal> позволяет отключить функцию + ввода сервера VRDE. Допустимые значения <literal>1</literal>, + отключающее функцию и null (<literal>""</literal>), + включающую эту функцию. Значение по умолчанию <literal>1</literal>. + Смотрите <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>Client/DisableAudio</literal> позволяет отключить функцию + аудио сервера VRDE. Допустимые значения <literal>1</literal>, + отключающее функцию и null (<literal>""</literal>), + включающую эту функцию. Значение по умолчанию <literal>1</literal>. + Смотрите <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>Client/DisableUSB</literal> позволяет отключить функцию + USB сервера VRDE. Допустимые значения <literal>1</literal>, + отключающее функцию и null (<literal>""</literal>), + включающую эту функцию. Значение по умолчанию <literal>1</literal>. + Смотрите <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>Client/DisableClipboard</literal> позволяет отключить + функцию буфера обмена сервера VRDE. Допустимые значения + <literal>1</literal>, отключающее функцию и null + (<literal>""</literal>), включающую эту функцию. + Используйте <literal>Client/DisableClipboard=</literal> для + включения этой функции. Значение по умолчанию <literal>1</literal>. + Смотрите <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>Client/DisableUpstreamAudio</literal> позволяет отключить + функцию загрузки аудио на сервер VRDE. Допустимые значения + <literal>1</literal>, отключающее функцию и null + (<literal>""</literal>), включающую эту функцию. + Используйте <literal>Client/DisableUpstreamAudio=</literal> для + включения этой функции. Значение по умолчанию <literal>1</literal>. + Смотрите <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>Client/DisableRDPDR</literal> позволяет отключить функцию + Перенаправления Устройств RDP Для Смарт-Карт сервера VRDE. + Допустимые значения <literal>1</literal>, отключающее функцию и + null (<literal>""</literal>), включающую эту функцию. + Значение по умолчанию <literal>1</literal>. Смотрите + <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>H3DRedirect/Enabled</literal> позволяет включить функцию + Перенаправления 3D сервера VRDE. Допустимые значения + <literal>1</literal>, включающее функцию и + null (<literal>""</literal>), отключающую эту функцию. + Смотрите <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>Security/Method</literal> указывает метод безопасности, + используемый для подключения. Смотрите <xref linkend="vrde-crypt" />. + </para><itemizedlist> + <listitem><para> + <literal>Negotiate</literal> принимает RDP подключения, имеющие + и повышенный (TLS) и стандартный протокол безопасности. Метод + безопасности оговаривается с клиентом. Это значение по умолчанию. + </para></listitem> + <listitem><para> + <literal>RDP</literal> принимает только RDP подключения со + стандартным протоколом безопасности. + </para></listitem> + <listitem><para> + <literal>TLS</literal> принимает только RDP подключения с + повышенным протоколом безопасности. Клиент должен поддерживать + TLS. + </para></listitem> + </itemizedlist></listitem> + <listitem><para> + <literal>Security/ServerCertificate</literal> указывает абсолютный + путь к сертификату сервера, используемому в подключении. + Смотрите <xref linkend="vrde-crypt" />. + </para></listitem> + <listitem><para> + <literal>Security/ServerPrivateKey</literal> указывает абсолютный + путь к приватному ключу сервера. Смотрите <xref linkend="vrde-crypt" />. + </para></listitem> + <listitem><para> + <literal>Security/CACertificate</literal> указывает абсолютный + путь к корневому самоподписанному сертификату. Смотрите + <xref linkend="vrde-crypt" />. + </para></listitem> + <listitem><para> + <literal>Audio/RateCorrectionMode</literal> указывает используемый + режим коррекции битрейта. + </para><itemizedlist> + <listitem><para> + <literal>VRDP_AUDIO_MODE_VOID</literal> отображает что + режим коррекции не используется. Используйте это значение + для снятия ранее установленного режима. + </para></listitem> + <listitem><para> + <literal>VRDP_AUDIO_MODE_RC</literal> указывает, что надо + использовать режим коррекции скорости. + </para></listitem> + <listitem><para> + <literal>VRDP_AUDIO_MODE_LPF</literal> указывает, что надо + использовать режим НЧ фильтра. + </para></listitem> + <listitem><para> + <literal>VRDP_AUDIO_MODE_CS</literal> указывает, что надо + использовать режим синхронизации клиента для предотвращения + незаполненности или переполнения очереди клиента. + </para></listitem> + </itemizedlist></listitem> + <listitem><para> + <literal>Audio/LogPath</literal> указывает абсолютный путь к файлу + журнала аудио. + </para></listitem> + </itemizedlist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-vrdevideochannelquality"> + <title>Указать качество изображения для перенаправления видео VRDP</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm <replaceable>имя-ВМ</replaceable> + vrdevideochannelquality</command> задает качество изображения как + значение уровня сжатия JPEG для перенаправления видео. Допустимые + значения между 10% и 100% включительно. Меньшие значения подразумевают + худшее качество, но более высокое сжатие. Смотрите + <xref linkend="vrde-videochannel" />. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-setvideomodehint"> + <title>Указать режим видео для гостевой ВМ</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> setvideomodehint</command> + задает используемый режим видео для гостевой ВМ. У вас должны + быть установлены Дополнения Гостевой ОС. Заметим, что данная + функция работает не для всех гостевых систем. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-setscreenlayout"> + <title>Задать макет экрана для монитора в гостевой ВМ</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> setscreenlayout</command> + может быть использована для настройки ВМ с несколькими мониторами. + Указанный экран гостевой ВМ может быть включен или отключен + или может быть настроен пользовательский макет экрана. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-screenshotpng"> + <title>Сделать снимок экрана с монитора виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> screenshotpng</command> делает + снимок экрана с монитора гостевой системы и сохраняет его в + формате PNG в указанном файле. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + <itemizedlist> + <listitem><para> + <replaceable>имя-файла</replaceable> задает имя создаваемого + PNG файла. + </para></listitem> + <listitem><para> + <replaceable>монитор</replaceable> задает номер монитора + откуда сделать снимок. Для ВМ с единственным монитором это + значение <literal>0</literal>. + </para></listitem> + </itemizedlist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording"> + <title>Включить или выключить запись сессии виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> recording</command> включает + или выключает запись сессии ВМ в WebM/VP8 файл. Допустимые значения + <literal>on</literal>, которое начинает запись, когда стартует + сессия ВМ и <literal>off</literal>, отключающее запись. Значение + по умолчанию <literal>off</literal>. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording-screens"> + <title>Задать экран виртуальной машины для записи</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> recording screens</command> + позволяет задать экран ВМ для записи. Запись для каждого + указанного вами экрана сохраняется в отдельный файл в папке + машины. Нельзя изменять эту настройку пока запись включена. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + <itemizedlist> + <listitem><para> + <literal>all</literal> указывает, что записывать все экраны ВМ. + </para></listitem> + <listitem><para> + <literal>none</literal> указывает, что не надо записывать экраны. + </para></listitem> + <listitem><para> + <replaceable>ID-экрана</replaceable> задает один или больше экранов + ВМ для записи. + </para></listitem> + </itemizedlist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording-filename"> + <title>Задать файл для сохранения записанной сессии виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> recording filename</command> + задает файл для сохранения записанной сессии. Нельзя изменять + эту настройку пока запись включена. + </para> + <para> + По умолчанию запись сохраняется в файл, находящийся в папке машины, + с именем ВМ в качестве имени файла и расширением + <filename>webm</filename>. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording-videores"> + <title>Задать разрешение записанного видео</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm <replaceable>имя-ВМ</replaceable> + recording videores</command> задает разрешение записанного видео в + пикселах. Нельзя изменять эту настройку пока включена запись. + </para> + <para> + Используйте инструмент Настройки для отображения настроек записи видео, + основанных на разрешении (размере кадра). Смотрите поле Размер Кадра + во вкладке Запись страницы Монитор для просмотра значения по умолчанию. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + <para> + Разрешение задается в виде + <replaceable>ширина</replaceable><literal>x</literal><replaceable>высота</replaceable>: + </para> + <itemizedlist> + <listitem><para> + <replaceable>ширина</replaceable> задает ширину в пикселах. + </para></listitem> + <listitem><para> + <replaceable>высота</replaceable> задает высоту в пикселах. + </para></listitem> + </itemizedlist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording-videorate"> + <title>Задать битрейт видео</title> + <remark role="help-copy-synopsis"/> +<!-- @todo r=andy Clarify rate. --> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> recording videorate</command> + задает битрейт видео в килобит в секунду. Увеличение этого + значения улучшает качество видео за счет увеличения размера + файла. Нельзя изменять это значение пока включена запись. + </para> + <para> + Используйте инструмент Настройки для отображения настроек + записи видео, основанных на размере кадра. Смотрите поле + Качество Видео вкладки Запись страницы Монитор для просмотра + значения по умолчанию. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording-videofps"> + <title>Задать максимальную частоту видео</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> recording videofps</command> + задает максимальную частоту видео для записи. Частота видео + измеряется в кадрах в секунду (FPS). Запись пропускает кадры, + имеющие частоту выше, чем указанный максимум. Увеличение + частоты уменьшает количество пропущенных кадров и увеличивает + размер файла. Нельзя изменять эту настройку пока включена + запись. + </para> + <para> + Используйте инструмент Настройки для отображения настроек записи + видео, основанных на размере кадра. Смотрите поле Частота Кадров во + вкладке Запись страницы Монитор для просмотра значения по + умолчанию. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording-maxtime"> + <title>Задать максимальное время записи видео</title> + <remark role="help-copy-synopsis"/> +<!-- @todo r=andy Clarify time format. --> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> recording maxtime</command> + задает максимальное время записи в секундах. Запись + останавливается по прошествии заданного количества секунд. + Если это значение равно нулю, запись продолжается пока + не будет остановлена принудительно. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording-maxfilesize"> + <title>Задать максимальный размер записанного видео</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> recording maxfilesize</command> + задает максимальный размер записанного видео в мегабайтах. + Запись останавливается когда файл достигает заданного размера. + Если это значение равно нулю, запись продолжается пока не будет + остановлена принудительно. Нельзя изменять эту настройку пока + включена запись. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-setcredentials"> + <title>Задать учетные данные для удаленного входа в виртуальные машины Windows</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>setcredentials</command> позволяет задать + учетные данные для удаленного входа в Windows ВМ. + Смотрите <xref linkend="autologon" />. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + <itemizedlist> + <listitem><para> + <replaceable>имя-пользователя</replaceable> задает имя + пользователя под которым необходимо производить вход + в Windows ВМ. + </para></listitem> + <listitem><para> + Опция + <option>--passwordfile=<replaceable>имя-файла</replaceable></option> + задает файл откуда брать пароль для + <replaceable>имя-пользователя</replaceable>. + </para><para> + Опция <option>--passwordfile</option> взаимоисключающая с опцией + <option>--password</option>. + </para></listitem> + <listitem><para> + Опция + <option>--password=<replaceable>пароль</replaceable></option> + задает пароль для <replaceable>имя-пользователя</replaceable>. + </para><remark> + Такой дизайн не соответствует рекомендациям Oracle по + безопасности. Вы не должны указывать пароль в командной + строке, потому что он может быть виден в списке процессов. + </remark><para> + Опция <option>--password</option> взаимоисключающая с опцией + <option>--passwordfile</option>. + </para></listitem> + <listitem><para> + Опция <option>--allowlocallogin</option> позволяет включать или + отключать локальные входы. Допустимые значения + <literal>on</literal> для включения локальных входов и + <literal>off</literal> для отключения. + </para></listitem> + </itemizedlist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-plugcpu"> + <title>Добавить виртуальный ЦПУ в виртуальную машину</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> plugcpu</command> добавляет + виртуальный ЦПУ в указанную ВМ если горячее подключение ЦПУ + включено. <replaceable>ID</replaceable> задает индекс + добавляемого виртуального ЦПУ и он должен быть в диапазоне + от 0 до максимального количества настроенных ЦПУ. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-unplugcpu"> + <title>Удалить виртуальный ЦПУ из виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> unplugcpu</command> удаляет + виртуальный ЦПУ из указанной ВМ если горячее подключение ЦПУ + включено. <replaceable>ID</replaceable> задает индекс + удаляемого виртуального ЦПУ и он должен быть в диапазоне + от 0 до максимального количества настроенных ЦПУ. Нельзя + удалить ЦПУ 0. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-cpuexecutioncap"> + <title>Установить максимальное время физического ЦПУ, используемого виртуальным ЦПУ</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> cpuexecutioncap</command> + задает максимальное количество времени физического ЦПУ + используемого виртуальным ЦПУ. Допустимые значения - это + процент между <literal>1</literal> и <literal>100</literal>. + Значение <literal>50</literal> указывает, что единственный + виртуальный ЦПУ может использовать до 50% физического ЦПУ. + По умолчанию установлено <literal>100</literal>. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-vm-process-priority"> + <title>Изменить приоритет процесса ВМ</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> vm-process-priority</command> + задает схему приоритета процесса ВМ используемую при старте + и работе ВМ. + </para> + <para> + Допустимые значения: + </para> + <itemizedlist> + <listitem><para> + <literal>default</literal> – Приоритет процесса + по умолчанию, определенный ОС. + </para></listitem> + <listitem><para> + <literal>flat</literal> – Предполагает политику + планирования, которая устанавливает для процесса + приоритет по умолчанию, при этом, всем потокам процесса + устанавливается один и тот же приоритет. + </para></listitem> + <listitem><para> + <literal>low</literal> – Предполагает политику + планирования, которая устанавливает приоритет процесса + в основном ниже приоритета по умолчанию ОС хоста. + </para></listitem> + <listitem><para> + <literal>normal</literal> – Предполагает политику + планирования, которая честно разделяет ресурсы ЦПУ с + другими процессами, имеющими приоритет по умолчанию + ОС хоста. + </para></listitem> + <listitem><para> + <literal>high</literal> – Предполагает политику + планирования, которая устанавливает приоритет процесса + выше приоритета по умолчанию ОС хоста. Эта политика + может повлиять на другие процессы, заставляя их ожидать + ресурса ЦПУ больше положенного времени, что может + привести к непредсказуемому поведению. + </para></listitem> + </itemizedlist> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-webcam-attach"> + <title>Подключить вебкамеру к виртуальной машине</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> webcam attach</command> + подключает вебкамеру к работающей ВМ. Задайте вебкамеру + через абсолютный путь к камере в ОС хоста или через псевдоним. + Используйте команду <command>VBoxManage list webcams</command> + для получения псевдонимов вебкамер. + </para> + <para> + Обратите внимание, что псевдоним <literal>.0</literal> - это + устройство получения видео по умолчанию в ОС хоста. + <literal>.1</literal> - это первое устройство получения видео, + <literal>.2</literal> - второе, и т.д. Порядок устройств + зависит от системы хоста. + </para> + <para> + Можно указать необязательные настройки в виде пар имя-значение + разделенных точкой с запятой (<literal>;</literal>). Эти + свойства позволяют настроить устройство эмулируемой вебкамеры. + </para> + <para> + Поддерживаются следующие настройки: + </para> + <variablelist> + <varlistentry> + <term><literal>MaxFramerate</literal></term> + <listitem><para> + Задает максимальную частоту кадров с которой видео отправляется + в ВМ. Задается в кадрах в секунду. Более высокие значения + увеличивают нагрузку на ЦПУ, так что этот параметр можно + использовать для уменьшения нагрузки на ЦПУ. Значение + по умолчанию - <literal>no maximum limit</literal>. Это значение + позволяет ВМ использовать любую частоту кадров, поддерживаемую + вебкамерой. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>MaxPayloadTransferSize</literal></term> + <listitem><para> + Задает максимальное количество байтов, принимаемого ВМ из + эмулируемой камеры в одном буфере. Значение по умолчанию - + <literal>3060</literal> байт, используемое некоторыми + вебкамерами. Если ВМ способна использовать буферы большего + размера, это может немного уменьшить нагрузку на ЦПУ. + Заметим, что некоторые гостевые ОС могу не поддерживать + более высокие значения <literal>MaxPayloadTransferSize</literal>. + </para></listitem> + </varlistentry> + </variablelist> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-webcam-detach"> + <title>Отключить вебкамеру от виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> webcam detach</command> + отключает вебкамеру от работающей ВМ. Задайте вебкамеру + через абсолютный путь к камере в ОС хоста или через псевдоним. + Используйте команду <command>VBoxManage list webcams</command> + для получения псевдонимов вебкамер. + </para> + <para> + Когда вебкамера отключается от хоста, ОС хоста определяет поведение + эмулируемой вебкамеры. + </para> + <itemizedlist> + <listitem><para> + <emphasis role="bold">Хосты Windows:</emphasis> Устройство + эмулируемой вебкамеры отключается от ВМ автоматически. + </para></listitem> + <listitem><para> + <emphasis role="bold">Хосты Mac OS X, которые работают + по крайней мере под OS X 10.7:</emphasis> Устройство + эмулируемой вебкамеры остается подключенным к ВМ. Его + необходимо отключить вручную, используя команду + <command>VBoxManage controlvm webcam detach</command>. + </para></listitem> + <listitem><para> + <emphasis role="bold">Хосты Linux:</emphasis> Устройство + эмулируемой вебкамеры отключается от ВМ автоматически + только если вебкамера активно транслирует видео. Если + эмулируемая камера не активна, необходимо отключить ее + вручную, используя команду <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> webcam detach</command>. + </para></listitem> + </itemizedlist> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-webcam-list"> + <title>Отобразить вебкамеры, подключенные к виртуальной машине</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> webcam list</command> показывает + вебкамеры, подключенные к работающей ВМ. Вывод отображает список + абсолютных путей или псевдонимов подключенных к ВМ вебкамер, + используя команду <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> webcam attach</command>. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-addencpassword"> + <title>Передать пароль шифрования в виртуальную машину</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> addencpassword</command> + обеспечивает шифрованную ВМ <replaceable>имя-ВМ</replaceable> + паролем шифрования для возможности старта в фоновом режиме. + Укажите абсолютный путь к файлу с паролем в хост-системе. + Если вместо <replaceable>имя-файла</replaceable> указан + <literal>-</literal>, <command>VBoxManage</command> предложит + ввести пароль. + </para> + <para> + Используйте опцию <option>--removeonsuspend</option> для указания + что пароль должен быть удален из памяти ВМ или сохранен когда + ВМ приостановлена. + </para> + <para> + Если ВМ приостановлена и пароль очищен используйте + <command>VBoxManage controlvm <replaceable>имя-ВМ</replaceable> + addencpassword</command>, чтобы указать пароль для продолжения + выполнения ВМ. Используйте эту функцию если не хотите оставлять + пароль в памяти ВМ пока ВМ приостановлена событием приостановки + хоста. + </para> + <note> + <para> + Можно шифровать данные, хранящиеся в образах жестких дисков, + испольуемых ВМ. &product-name; использует алгоритм AES в режиме + XTS и поддерживает 128 и 256 битные ключи шифрования данных + (DEK). Зашифрованный DEK хранится в свойствах носителя и + расшифровывается при старте ВМ когда вы передаете пароль + шифрования. + </para> + </note> + <para> + Используйте команду <command>VBoxManage encryptmedium</command> + для создания носителя зашифрованного DEK. Смотрите + <xref linkend="diskencryption-encryption" />. + </para> + <para> + Графический интерфейс &product-name; предложит ввести пароль + шифрования при старте зашифрованной ВМ. + </para> + <para> + Используйте следующую команду для старта в фоновом режиме + зашифрованной ВМ: + </para> +<screen> + $ VBoxManage startvm <replaceable>имя-ВМ</replaceable> --type headless + </screen> + <para> + Затем, используйте следующую команду для передачи пароля + шифрования: + </para> +<screen> + $ VBoxManage <replaceable>имя-ВМ</replaceable> controlvm addencpassword <replaceable>имя-ВМ</replaceable> - + Пароль: <replaceable>пароль-шифрования</replaceable> + </screen> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-removeencpassword"> + <title>Отозвать пароль шифрования из виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> removeencpassword</command> + отзывает указанный пароль шифрования для всех зашифрованных + носителей, подключенных к ВМ. + </para> + <para> + <replaceable>ID</replaceable> - идентификатор пароля, который + вы хотите отозвать. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-removeallencpasswords"> + <title>Отозвать все пароли шифрования из виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm <replaceable>имя-ВМ</replaceable> + removeallencpasswords</command> отзывает все пароли шифрования + для всех зашифрованных носителей подключенных к ВМ. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-changeuartmode"> + <title>Изменить режим подключения виртуального последовательного порта в виртуальной машине</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> changeuartmode</command> + изменяет режим подключения для указанного виртуального + последовательного порта. Допустимые значения последовательного + порта - это числа, начинающиеся с <literal>1</literal>. + </para> + <para> + Эта команда не влияет прямо на состояние выполнения ВМ. + </para> + <variablelist> + <varlistentry> + <term>disconnected</term> + <listitem><para> + Отключает устройство. + </para></listitem> + </varlistentry> + <varlistentry> + <term>server <replaceable>имя-канала</replaceable></term> + <listitem><para> + Указывает имя канала сервера. + </para></listitem> + </varlistentry> + <varlistentry> + <term>client <replaceable>имя-канала</replaceable></term> + <listitem><para> + Указывает имя канала клиента. + </para></listitem> + </varlistentry> + <varlistentry> + <term>tcpserver <replaceable>порт</replaceable></term> + <listitem><para> + Указывает номер порта сервера TCP. + </para></listitem> + </varlistentry> + <varlistentry> + <term>tcpclient <replaceable>имя-хоста</replaceable>:<replaceable>порт</replaceable></term> + <listitem><para> + Указывает имя хоста и номер порта клиента TCP. + </para></listitem> + </varlistentry> + <varlistentry> + <term>file <replaceable>имя-файла</replaceable></term> + <listitem><para> + Указывает имя файла. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>имя-устройства</replaceable></term> + <listitem><para> + Указывает имя устройства. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-autostart-enabled"> + <title>Включить автостарт ВМ во время загрузки хост-системы</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> autostart-enabled</command> + указывает включить или отключить автоматический старт ВМ во + время загрузки хост-системы. Вы должны произвести некоторую + настройку хост-системы перед тем как вы сможете использовать + данный функционал. Смотрите <xref linkend="autostart" />. + Допустимые значения <literal>on</literal>, включающую + функцию автостарта для ВМ и <literal>off</literal>, + отключающую ее. Значение по умолчанию <literal>off</literal>. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-autostart-delay"> + <title>Установить задержку старта ВМ во время загрузки хост-системы</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage controlvm + <replaceable>имя-ВМ</replaceable> autostart-delay</command> + задает задержку в секундах перед тем, как ВМ будет запущена + во время загрузки хост-системы. Смотрите + <xref linkend="autostart" />. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда временно останавливает выполнение ВМ + <filename>ol7</filename>. + </para> +<screen>$ VBoxManage controlvm ol7 pause</screen> + <para> + Следующая команда настраивает операции буфера обмена для ВМ + <filename>ol7</filename>. Копирование данных буфера обмена + разрешено в обоих направлениях между хостом и гостевой + системой. + </para> +<screen>$ VBoxManage controlvm ol7 clipboard mode bidirectional</screen> + </refsect1> + + <refsect1> + <title>Смотрите также</title> + <para> + <xref linkend="vboxmanage-list" />, + <xref linkend="vboxmanage-modifyvm" />, + <xref linkend="vboxmanage-startvm" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-convertfromraw.xml b/doc/manual/ru_RU/man_VBoxManage-convertfromraw.xml new file mode 100644 index 00000000..7e658e03 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-convertfromraw.xml @@ -0,0 +1,248 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage convertfromraw +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-convertfromraw" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage convertfromraw</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-convertfromraw</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-convertfromraw</refname> + <refpurpose>преобразует образ raw диска в образ виртуального диска</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <cmdsynopsis id="synopsis-vboxmanage-convertfromraw-file"> + <command>VBoxManage convertfromraw</command> + <arg choice="req"><replaceable>входной-файл</replaceable></arg> + <arg choice="req"><replaceable>выходной-файл</replaceable></arg> + <arg>--format=<group choice="plain"> + <arg choice="plain">VDI</arg> + <arg choice="plain">VMDK</arg> + <arg choice="plain">VHD</arg> + </group></arg> + <arg>--uuid=<replaceable>uuid</replaceable></arg> + <arg>--variant=Standard,Fixed,Split2G,Stream,ESX</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-convertfromraw-stdin"> + <command>VBoxManage convertfromraw stdin</command> + <arg choice="req"><replaceable>выходной-файл</replaceable></arg> + <arg>--format=<group choice="plain"> + <arg choice="plain">VDI</arg> + <arg choice="plain">VMDK</arg> + <arg choice="plain">VHD</arg> + </group></arg> + <arg>--uuid=<replaceable>uuid</replaceable></arg> + <arg>--variant=Standard,Fixed,Split2G,Stream,ESX</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage convertfromraw</command> позволяет + преобразовать образ raw диска в образ виртуального диска + &product-name; (VDI). + </para> + <note> + <para> + Для совместимости с ранними версиями &product-name;, можно + использовать команду <command>VBoxManage convertdd</command> + вместо команды <command>VBoxManage convertfromraw</command>. + </para> + </note> + <refsect2 id="vboxmanage-convertfromraw-file"> + <title>Преобразовать файл raw диска в файл образа виртуального диска</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage convertfromraw</command> + преобразует указанный входной файл образа raw диска в + VDI файл &product-name; + </para> + <variablelist> + <varlistentry> + <term><replaceable>входной-файл</replaceable></term> + <listitem><para> + Указывает имя файла образа raw диска для преобразования. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>выходной-файл</replaceable></term> + <listitem><para> + Указывает имя файла, куда записывать VDI данные. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--format=VDI | VMDK | VHD</option></term> + <listitem><para> + Задает формат формат создаваемого образа диска. Допустимыми + значениями являются <literal>VDI</literal>, + <literal>VMDK</literal>, и <literal>VHD</literal>. Формат + по умолчанию <literal>VDI</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Задает Универсальный Уникальный Идентификатор (UUID) + выходного файла. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--variant=Standard,Fixed,Split2G,Stream,ESX</option></term> + <listitem><para> + Задает требуемые варианты формата выходного файла. Это + список значений вариантов разделенный запятыми. Далее + указаны допустимые значения: + </para><itemizedlist> + <listitem><para> + <literal>Standard</literal> - тип образа диска + по умолчанию. Динамически расширяющийся файл. + </para></listitem> + <listitem><para> + <literal>Fixed</literal> использует файл образа диска + фиксированного размера. + </para></listitem> + <listitem><para> + <literal>Split2G</literal> показывает что образ диска + разделяется на сегменты по 2 ГБ. Это значение только + для VMDK. + </para></listitem> + <listitem><para> + <literal>Stream</literal> оптимизирует образ диска + для загрузки. Это значение только для VMDK. + </para></listitem> + <listitem><para> + <literal>ESX</literal> используется в некоторых + продуктах VMWare. Это значение только для VMDK. + </para></listitem> + </itemizedlist><para> + Заметим, что не все комбинации вариантов допустимы. + Указание несовместимых значений вариантов в списке + ведет к выдаче сообщения об ошибке. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-convertfromraw-stdin"> + <title>Преобразовать raw данные из стандартного потока ввода в файл образа виртуального диска</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage convertfromraw stdin</command> + читает содержимое образа диска из стандартного потока ввода. + Рассматривайте использование команды этой формы в + последовательности каналов. + </para> + <variablelist> + <varlistentry> + <term><replaceable>выходной-файл</replaceable></term> + <listitem><para> + Указывает имя файла, куда записывать VDI данные. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--format=VDI | VMDK | VHD</option></term> + <listitem><para> + Задает формат формат создаваемого образа диска. Допустимыми + значениями являются <literal>VDI</literal>, + <literal>VMDK</literal> и <literal>VHD</literal>. Формат + по умолчанию <literal>VDI</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Задает UUID выходного файла. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--variant=Standard,Fixed,Split2G,Stream,ESX</option></term> + <listitem><para> + Задает требуемые варианты формата выходного файла. Это + список значений вариантов разделенный запятыми. Далее + указаны допустимые значения: + </para><itemizedlist> + <listitem><para> + <literal>Standard</literal> - тип образа диска + по умолчанию. Динамически расширяющийся файл. + </para></listitem> + <listitem><para> + <literal>Fixed</literal> использует файл образа диска + фиксированного размера. + </para></listitem> + <listitem><para> + <literal>Split2G</literal> показывает что образ диска + разделяется на сегменты по 2 ГБ. Это значение только + для VMDK. + </para></listitem> + <listitem><para> + <literal>Stream</literal> оптимизирует образ диска + для загрузки. Это значение только для VMDK. + </para></listitem> + <listitem><para> + <literal>ESX</literal> используется в некоторых + продуктах VMWare. Это значение только для VMDK. + </para></listitem> + </itemizedlist><para> + Заметим, что не все комбинации вариантов допустимы. + Указание несовместимых значений вариантов в списке + ведет к выдаче сообщения об ошибке. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда преобразует входной файл образа raw диска + <filename>disk01.raw</filename>. Выходной файл - это VDI образ + диска называемый <filename>disk02.vdi</filename>. + </para> +<screen>$ VBoxManage convertfromraw disk01.raw disk02.vdi</screen> + <para> + Следующая команда преобразует входной файл образа raw диска + <filename>disk01.raw</filename>. Выходной файл - это VMDK образ + диска называемый <filename>disk02.vmdk</filename>. + </para> +<screen>$ VBoxManage convertfromraw disk01.raw disk02.vmdk --format VMDK</screen> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-createmedium.xml b/doc/manual/ru_RU/man_VBoxManage-createmedium.xml new file mode 100644 index 00000000..74e32546 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-createmedium.xml @@ -0,0 +1,219 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage createmedium +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-createmedium" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage createmedium</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-createmedium</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-createmedium</refname> + <refpurpose>создает новый носитель</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-createmedium"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage createmedium</command> + <group> + <arg choice="plain"><replaceable>disk</replaceable></arg> + <arg choice="plain"><replaceable>dvd</replaceable></arg> + <arg choice="plain"><replaceable>floppy</replaceable></arg> + </group> + <arg choice="req">--filename=<replaceable>имя-файла</replaceable></arg> + <group> + <arg choice="plain">--size=<replaceable>мегабайты</replaceable></arg> + <arg choice="plain">--sizebyte=<replaceable>байты</replaceable></arg> + </group> + <arg>--diffparent=<group choice="plain"> + <arg choice="plain"><replaceable>UUID</replaceable></arg> + <arg choice="plain"><replaceable>имя-файла</replaceable></arg> + </group></arg> + <arg>--format=<group choice="plain"> + <arg choice="plain"><replaceable>VDI</replaceable></arg> + <arg choice="plain"><replaceable>VMDK</replaceable></arg> + <arg choice="plain"><replaceable>VHD</replaceable></arg> + </group></arg> + <arg>--variant Standard,Fixed,Split2G,Stream,ESX,Formatted,RawDisk</arg> + <arg choice="plain" rep="repeat">--property + <replaceable>имя</replaceable>=<replaceable>значение</replaceable></arg> + <arg choice="plain" rep="repeat">--property-file + <replaceable>имя</replaceable>=<replaceable>/путь/к/файлу/со/значением</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage createmedium</command> создает новый + носитель, такой как файл образа диска. + </para> + <note> + <para> + Для совместимости с ранними версиями &product-name; можно + использовать команды <command>createvdi</command> и + <command>createhd</command> вместо команды + <command>createmedium</command>. + </para> + </note> + <variablelist> + <varlistentry> + <term>disk | dvd | floppy</term> + <listitem><para> + Указывает тип носителя. Значение по умолчанию + <literal>disk</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--filename=<replaceable>имя-файла</replaceable></option></term> + <listitem><para> + Указывает абсолютный путь к файлу в файловой системе хоста. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--size=<replaceable>мегабайты</replaceable></option></term> + <listitem><para> + Задает емкость образа в мегабайтах. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--sizebyte=<replaceable>байты</replaceable></option></term> + <listitem><para> + Задает емкость образа в байтах. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--diffparent=<replaceable>UUID</replaceable> | <replaceable>имя-файла</replaceable></option></term> + <listitem><para> + Указывает Универсальный Уникальный Идентификатор (UUID) или + абсолютный путь к родительскому файлу разностного образа в + файловой системе хоста. + </para><para> + Используйте этот файл для совместного использования + базового образа диска между ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--format=VDI | VMDK | VHD</option></term> + <listitem><para> + Задает формат выходного файла. Допустимые форматы + <literal>VDI</literal>, <literal>VMDK</literal> и + <literal>VHD</literal>. Формат по умолчанию + <literal>VDI</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--variant=Standard,Fixed,Split2G,Stream,ESX,Formatted,RawDisk</option></term> + <listitem><para> + Задает варианты формата файла для целевого носителя в + виде списка значений разделенных запятыми. Допустимы + следующие значения: + </para><itemizedlist> + <listitem><para> + <literal>Standard</literal> - это тип образа диска + по умолчанию. Динамически расширяющийся файл. + </para></listitem> + <listitem><para> + <literal>Fixed</literal> использует файл образа диска + фиксированного размера. + </para></listitem> + <listitem><para> + <literal>Split2G</literal> показывает, что образ диска + разделяется на сегменты по 2 ГБ. Это значение только + для VMDK. + </para></listitem> + <listitem><para> + <literal>Stream</literal> оптимизирует образ диска + для загрузки. Это значение только для VMDK. + </para></listitem> + <listitem><para> + <literal>ESX</literal> используется в некоторых + продуктах VMWare. Это значение только для VMDK. + </para></listitem> + <listitem><para> + <literal>Formatted</literal> + </para><para> + Только для образов флоппи. Автоматически форматирует + носитель. + </para></listitem> + <listitem><para> + <literal>RawDisk</literal> используется для создания + raw дисков. Это значение только для VMDK. + </para><para> + + </para></listitem> + </itemizedlist><para> + Заметим, что не все комбинации вариантов допустимы. Указание + несовместимых значений вариантов в списке ведет к выдаче + сообщения об ошибке. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--property <replaceable>имя</replaceable>=<replaceable>значение</replaceable></option></term> + <listitem><para> + Задает требуемые параметры, зависящие от формата файла в + форме <literal>ключ=значение</literal>. Опционально. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--property-file <replaceable>name + </replaceable>=<replaceable>/path/to/file/with/value</replaceable></option></term> + <listitem><para> + Задает требуемые параметры, зависящие от формата файла в + форме <literal>key=файл/со/значением</literal>. Значение + берется из файла. Опционально. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда создает новый файл образа диска, называемый + <filename>disk01.vdi</filename>. Файл имеет размер 1024 мегабайта. + </para> +<screen>$ VBoxManage createmedium --filename disk01.vdi --size 1024</screen> + <para> + Следующая команда создает новый файл образа флоппи диска, называемый + <filename>floppy01.vdi</filename>. Файл имеет размер 1 мегабайт. + </para> +<screen>$ VBoxManage createmedium floppy --filename floppy01.img --size 1</screen> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-createvm.xml b/doc/manual/ru_RU/man_VBoxManage-createvm.xml new file mode 100644 index 00000000..788c5cc5 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-createvm.xml @@ -0,0 +1,175 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage createvm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-createvm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage createvm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-createvm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-createvm</refname> + <refpurpose>создает новую виртуальную машину</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-createvm"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage createvm</command> + <arg choice="req">--name=<replaceable>имя-ВМ</replaceable></arg> + <arg>--basefolder=<replaceable>основная-папка</replaceable></arg> + <arg>--default</arg> + <arg>--group=<replaceable>ID-группы</replaceable>,...</arg> + <arg>--ostype=<replaceable>тип-ОС</replaceable></arg> + <arg>--register</arg> + <arg>--uuid=<replaceable>uuid</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage createvm</command> создает новый + XML-файл определения виртуальной машины (ВМ). + </para> + <para> + Необходимо указать имя ВМ, используя <option>--name + <replaceable>имя-ВМ</replaceable></option>. Это имя по умолчанию + используется как имя файла настроек, имеющего расширение + <filename>.vbox</filename>, а также как имя папки машины, + находящейся в директории <filename>$HOME/VirtualBox VMs</filename>. + </para> + <para> + Фактическое имя файла может не соответствовать имени ВМ если + оно нарушает требования к имени файла ОС хоста (например + использование разделителя пути или других зарезервированных + символов, все это будет заменено на символ подстановки). Если + ВМ будет позднее переименована, имена файла и папки будут + обновлены автоматически чтобы соответствовать новому имени. + </para> + </refsect1> + + <refsect1> + <title>Опции команды</title> + <para> + В дополнение к требуемому указанию имени или UUID ВМ, можно + указать следующие опции: + </para> + <variablelist> + <varlistentry> + <term><option>--basefolder=<replaceable>основная-папка</replaceable></option></term> + <listitem><para> + Задает имя папки в которую сохранять файл конфигурации + машины для новой ВМ. + </para><para> + Обратите внимание, что имена файла и папки не изменяются если + переименовать ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--default</option></term> + <listitem><para> + Применяет аппаратную конфигурацию по умолчанию для указанной + гостевой ОС. По умолчанию, ВМ создается с минимальным + оборудованием. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--group=<replaceable>ID-группы</replaceable>,...</option></term> + <listitem><para> + Назначает ВМ на указанные группы. Если указывается более + чем одна группа, разделите их запятыми. + </para><para> + Заметим, что каждая группа идентифицируется через ID группы, + начинающаяся с символа слэш (<literal>/</literal>), поэтому + группы могут быть вложенные. По умолчанию, ВМ всегда + назначается на группу <literal>/</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ostype=<replaceable>тип-ОС</replaceable></option></term> + <listitem><para> + Указывает гостевую ОС для запуска в ВМ. Запустите команду + <command>VBoxManage list ostypes</command> для просмотра + доступных типов ОС. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--register</option></term> + <listitem><para> + Регистрирует ВМ в &product-name;. По умолчанию команда + <command>VBoxManage createvm</command> создает только + XML конфигурацию для ВМ но не регистрирует ВМ. Если не + регистрировать ВМ при создании, можно запустить команду + <command>VBoxManage registervm</command> после создания. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Задает Универсальный Уникальный Идентификатор (UUID) ВМ. + Убедитесь что этот UUID уникален в пространстве имен + &product-name; хоста или его членства в группах ВМ, если + хотите зарегистрировать ВМ. По умолчанию &product-name; + предоставляет UUID. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда создает ВМ называемую <literal>vm2</literal> + где планируется запускать 64 битную версию Orace Linux. + </para> +<screen>$ VBoxManage createvm --name "vm2" --ostype "Oracle_64"</screen> + <para> + Следующая команда создает и регистрирует ВМ называемую + <literal>vm3</literal>. + </para> +<screen>$ VBoxManage createvm --name "vm3" --register</screen> + </refsect1> + + <refsect1> + <title>Смотрите также</title> + <para> + <xref linkend="vboxmanage-list" />, + <xref linkend="vboxmanage-registervm" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-debugvm.xml b/doc/manual/ru_RU/man_VBoxManage-debugvm.xml new file mode 100644 index 00000000..0d7963b3 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-debugvm.xml @@ -0,0 +1,673 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage debugvm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-debugvm" lang="en"> + + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage debugvm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-debugvm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-debugvm</refname> + <refpurpose>интроспекция и гостевая отладка</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-dumpvmcore"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">dumpvmcore</arg> + <arg>--filename=<replaceable>name</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-info"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">info</arg> + <arg choice="req"><replaceable>элемент</replaceable></arg> + <arg rep="repeat"><replaceable>аргументы</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-injectnmi"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">injectnmi</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-log"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">log</arg> + <group><arg>--release</arg><arg>--debug</arg></group> + <arg rep="repeat"><replaceable>настройки-группы</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-logdest"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">logdest</arg> + <group><arg>--release</arg><arg>--debug</arg></group> + <arg rep="repeat"><replaceable>назначения</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-logflags"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">logflags</arg> + <group><arg>--release</arg><arg>--debug</arg></group> + <arg rep="repeat"><replaceable>флаги</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-osdetect"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">osdetect</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-osinfo"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">osinfo</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-osdmesg"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">osdmesg</arg> + <arg>--lines=<replaceable>строки</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-getregisters"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">getregisters</arg> + <arg>--cpu=<replaceable>id</replaceable></arg> + <arg rep="repeat"><replaceable>набор-регистров.имя-регистра</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-setregisters"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">setregisters</arg> + <arg>--cpu=<replaceable>id</replaceable></arg> + <arg rep="repeat"><replaceable>набор-регистров.имя-регистра</replaceable>=<replaceable>значение</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-show"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">show</arg> + <group><arg>--human-readable</arg><arg>--sh-export</arg><arg>--sh-eval</arg><arg>--cmd-set</arg></group> + <arg rep="repeat"><replaceable>элемент-настроек</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-stack"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">stack</arg> + <arg>--cpu=<replaceable>id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-statistics"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">statistics</arg> + <arg>--reset</arg> + <arg>--descriptions</arg> + <arg>--pattern=<replaceable>шаблон</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-guestsample"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">guestsample</arg> + <arg>--filename=<replaceable>имя-файла</replaceable></arg> + <arg>--sample-interval-us=<replaceable>интервал</replaceable></arg> + <arg>--sample-time-us=<replaceable>время</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + <refsect1> + <title>Описание</title> + + <para> + Команды "debugvm" предназначены для экспертов, которые хотят разобраться в деталях + исполнения виртуальной машины. Как и отладчик VM описанный в + <xref linkend="ts_debugger" />, эти команды полезны только если хорошо разбираетесь + в архитектуре PC и знаете как отлаживать программное обеспечение. + </para> + + <refsect2 id="vboxmanage-debugvm-common-options"> + <title>Общие параметры</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>Все подкоманды <command>debugvm</command> выполняются в работающей виртуальной + машине:</para> + <variablelist> + <varlistentry> + <term><replaceable>uuid|имя-ВМ</replaceable></term> + <listitem><para>Или UUID или имя (чувствительно к регистру) ВМ.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-dumpvmcore"> + <title>debugvm dumpvmcore</title> + <remark role="help-copy-synopsis"/> + <para> + Создает файл системного дампа указанной ВМ. Этот файл будет иметь + стандартный формат ELF ядра (с пользовательскими секциями); Смотрите + <xref linkend="ts_guest-core-format" />. + </para> + <para> + Команда соответствует команде <command>writecore</command> отладчика. + </para> + <variablelist> + <varlistentry> + <term><option>--filename=<replaceable>имя-файла</replaceable></option></term> + <listitem><para>Имя выходного файла.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-info"> + <title>debugvm info</title> + <remark role="help-copy-synopsis"/> + <para> + Отображает информацию относительно VMM, эмуляции устройств и + назначенных драйверов. + </para> + <para> + Команда соответствует команде <command>info</command> отладчика. + </para> + <variablelist> + <varlistentry> + <term><replaceable>элемент</replaceable></term> + <listitem> + <para>Имя элемента для отображения. Специальное имя + <option>help</option> показывает список всех доступных + элементов и подсказок по необязательным аргументам.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><replaceable>аргументы</replaceable></term> + <listitem> + <para>Необязательная строка аргументов для обработчика элемента. + Большинство элементов не требуют дополнительных аргументов. Нераспознанные + аргументы в основном игнорируются. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-injectnmi"> + <title>debugvm injectnmi</title> + <remark role="help-copy-synopsis"/> + <para> + Внедряет немаскируемое прерывание (NMI) в гостевую систему. Это может быть + полезно для определенных сценариев отладки. Что точно произойдет, зависит + от гостевой операционной системы, однако NMI может вызвать крах всей + гостевой ОС. Не используйте если не знаете что вы делаете. + </para> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-log"> + <title>debugvm log</title> + <remark role="help-copy-synopsis"/> + <para> + Изменяет настройки группы для журналирования ВМ процесса в режимах отладки + (<option>--debug</option>) или выпуска (<option>--release</option>). + </para> + <para> + <replaceable>настройки-группы</replaceable> в основном строки в форме + <computeroutput>em.e.f.l</computeroutput>, <computeroutput>hm=~0</computeroutput> + и <computeroutput>-em.f</computeroutput>. Поддерживаются базовые подстановочные + знаки для сопоставления групп. Группа + <computeroutput>all</computeroutput> - это псевдоним для всех групп. + </para> + <para> + Пожалуйста, имейте ввиду, что настройки группы применяются как модификация + текущих настроек. + </para> + <para> + Эта команда соответствует команде <command>log</command> отладчика. + </para> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-logdest"> + <title>debugvm logdest</title> + <remark role="help-copy-synopsis"/> + <para> + Изменяет настройки назначения для журналирования ВМ процесса в режимах + отладки (<option>--debug</option>) или выпуска (<option>--release</option>). + Более подробную информацию по формату назначения лучше посмотреть в + src/VBox/Runtime/common/log/log.cpp. + </para> + <para> + <replaceable>назначения</replaceable> - это одна или несколько мнемоник, + которые могут предваряться "no" для их отключения. Некоторые из них берут + значения после разделителей ":" или "=". Множественные мнемоники могут + разделяться через пробел или задаваться как отдельные аргументы в командной + строке. + </para> + <para> + Список доступных назначений: + </para> + <variablelist> + <varlistentry> + <term><option>file[=<replaceable>файл</replaceable>], nofile</option></term> + <listitem><para>Указывает файл журнала. Если файл журнала не указан, он + будет сгенерирован на основе текущего времени UTC и имени процесса ВМ и + помещен в текущую директорию процесса ВМ. Заметим, что данная команда + не имеет силы если файл журнала уже открыт. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>dir=<replaceable>директория</replaceable>, nodir</option></term> + <listitem><para>Указывает директорию для файлов журналов. Заметим, что данная + команда не имеет силы если файл журнала уже открыт. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>history=<replaceable>количество</replaceable>, nohistory</option></term> + <listitem><para>Ненулевые значения включают историю журналов. Значение показывает + сколько хранить старых файлов журналов. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>histsize=<replaceable>байт</replaceable></option></term> + <listitem><para>Максимальный размер файла журнала перед сменой файла. По умолчанию бесконечно.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>histtime=<replaceable>секунды</replaceable></option></term> + <listitem><para>Максимальный возраст (в секундах) файла журнала перед сменой файла. По умолчанию бесконечно.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>ringbuffer, noringbuffer</option></term> + <listitem><para>Записывать журнал только в буфер журнала до явного сброса на диск + (например через assertion). Это быстро и сохраняет дисковое пространство.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>stdout, nostdout</option></term> + <listitem><para>Записывать содержимое журнала в стандартный поток вывода.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>stdout, nostdout</option></term> + <listitem><para>Записывать содержимое журнала в стандартный поток ошибок.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>debugger, nodebugger</option></term> + <listitem><para>Записывать содержимое журнала в отладчик, если поддерживается ОС хоста.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>com, nocom</option></term> + <listitem><para>Записывать содержимое журнала в COM порт. Применимо только для raw-режима и ring-0 журналирования.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>user, nouser</option></term> + <listitem><para>Пользовательское назначение, не имеющее значения для процессов ВМ.</para></listitem> + </varlistentry> + </variablelist> + <para> + Эта команда соответствует команде <command>logdest</command> отладчика. + </para> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-logflags"> + <title>debugvm logflags</title> + <remark role="help-copy-synopsis"/> + <para> + Изменяет флаги журналирования ВМ процесса в режимах отладки + (<option>--debug</option>) или выпуска (<option>--release</option>). Пожалуйста, + имейте ввиду, что изменения применяются к существующим и не подменяют их. + </para> + <para> + <replaceable>флаги</replaceable> - это список мнемоник, опционально предваряемые + "no", "!", "~" или "-" для смены значения на противоположное. Префикс "+" может + использоваться для отмены предыдущего противоположного значения или как разделитель, + хотя лучше использовать пробел или отдельные аргументы. + </para> + <para> + Список мнемоник флагов с их противоположной формой, где применимо + (звездочка показывает значение по умолчанию): + </para> + <variablelist> + <varlistentry> + <term><option>enabled*, disabled</option></term> + <listitem><para>Включает или выключает журналирование.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>buffered, unbuffered*</option></term> + <listitem><para>Включает буферизацию вывода журнала перед записью в назначение.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>writethrough(/writethru)</option></term> + <listitem><para>Открывать ли файл назначения со сквозной буферизацией или нет.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>flush</option></term> + <listitem><para>Включает сброс выходного файла на диск после каждой записи в журнал.</para></listitem> + </varlistentry> + <!-- Prefixes --> + <varlistentry> + <term><option>lockcnts</option></term> + <listitem><para>Предварять каждую строку журнала количеством блокировок текущего потока.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>cpuid</option></term> + <listitem><para>Предварять каждую строку журнала ID текущего ЦПУ.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>pid</option></term> + <listitem><para>Предварять каждую строку журнала ID текущего процесса.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>flagno</option></term> + <listitem><para>Предварять каждую строку журнала числовыми значениями флагов соответствующих записи в журанал.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>flag</option></term> + <listitem><para>Предварять каждую строку журнала мнемониками флагов соответствующих записи в журанал.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>groupno</option></term> + <listitem><para>Предварять каждую строку журнала номером группы соответствующей записи в журанал.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>group</option></term> + <listitem><para>Предварять каждую строку журнала именем группы соответствующей записи в журанал.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>tid</option></term> + <listitem><para>Предварять каждую строку журнала ID текущего потока.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>thread</option></term> + <listitem><para>Предварять каждую строку журнала именем текущего потока.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>time</option></term> + <listitem><para>Предварять каждую строку журнала текущим временем UTC.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>timeprog</option></term> + <listitem><para>Предварять каждую строку журнала текущим монотонным временем, прошедшим с момента старта программы.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>msprog</option></term> + <listitem><para>Предварять каждую строку журнала текущим монотонным временем в милисекундах, прошедшим с момента старта программы.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>ts</option></term> + <listitem><para>Предварять каждую строку журнала текущим монотонным временем в наносекундах.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>tsc</option></term> + <listitem><para>Предварять каждую строку журнала текущим временем ЦПУ (TSC).</para></listitem> + </varlistentry> + <varlistentry> + <term><option>rel, abs*</option></term> + <listitem><para>Выбирает как отображать префиксы <computeroutput>ts</computeroutput> и + <computeroutput>tsc</computeroutput>: как время относительно предыдущей строки журнала + или как абсолютное время.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>hex*, dec</option></term> + <listitem><para>Выбирает как форматировать префиксы <computeroutput>ts</computeroutput> и + <computeroutput>tsc</computeroutput>: как шестнадцатиричные значения или как десятичные. + </para></listitem> + </varlistentry> + + <!-- Suffixes and weird stuff. --> + <varlistentry> + <term><option>custom</option></term> + <listitem><para>Пользовательский префикс записи журнала. По умолчанию не имеет значения для ВМ процессов.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>usecrlf, uself*</option></term> + <listitem><para>Выводить используя окончания строк в стиле DOS (CRLF) или UNIX (LF).</para></listitem> + </varlistentry> + <varlistentry> + <term><option>overwrite*, append</option></term> + <listitem><para>Перезаписывать файл назначения или добавлять строки в конец файла.</para></listitem> + </varlistentry> + </variablelist> + + <para> + Эта команда соответствует команде <command>logflags</command> отладчика. + </para> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-osdetect"> + <title>debugvm osdetect</title> + <remark role="help-copy-synopsis"/> + <para> + Заставляет отладчик VMM (заново) определить гостевую операционную систему (ОС). + Команда сначала загружает все плагины отладчика. + </para> + <para> + Эта команда соответствует команде <command>detect</command> отладчика. + </para> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-osinfo"> + <title>debugvm osinfo</title> + <remark role="help-copy-synopsis"/> + <para> + Отображает информацию о гостевой операционной системе (ОС), ранее + определенной отладчиком VMM. + </para> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-osdmesg"> + <title>debugvm osdmesg</title> + <remark role="help-copy-synopsis"/> + <para> + Отображает журнал ядра гостевой ОС, если она определена и поддерживается. + </para> + <variablelist> + <varlistentry> + <term><option>--lines=<replaceable>строки</replaceable></option></term> + <listitem><para>Количество отображаемых строк. Счет ведется с конца журнала. + По умолчанию бесконечно.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-getregisters"> + <title>debugvm getregisters</title> + <remark role="help-copy-synopsis"/> + <para> + Получает значения регистров гостевых ЦПУ и эмулируемых устройств. + </para> + <variablelist> + <varlistentry> + <term><replaceable>набор-регистров.имя-регистра</replaceable></term> + <listitem> + <para>Один или несколько регистров, где каждый указывается в следующих формах:</para> + <orderedlist> + <listitem><para>набор-регистров.имя-регистра.под-поле</para></listitem> + <listitem><para>набор-регистров.имя-регистра</para></listitem> + <listitem><para>имя-регистра-цпу.под-поле</para></listitem> + <listitem><para>имя-регистра-цпу</para></listitem> + <listitem><para>all</para></listitem> + </orderedlist> + <para>Форма <replaceable>all</replaceable> показывает все регистры (без под-полей). + Имена регистров не чувствительно к регистру. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--cpu=<replaceable>id</replaceable></option></term> + <listitem><para>Выбирает набор регистров ЦПУ при указании только + регистра ЦПУ (3-я и 4-я формы). По умолчанию 0.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-setregisters"> + <title>debugvm setregisters</title> + <remark role="help-copy-synopsis"/> + <para> + Изменяет значения регистров гостевой ОС и эмулируемых устройств. + </para> + <variablelist> + <varlistentry> + <term><replaceable>набор-регистров.имя-регистра=значение</replaceable></term> + <listitem> + <para>Присвоение значений одному или нескольким регистрами, где каждый + указывается в следующих формах:</para> + <orderedlist> + <listitem><para>набор-регистров.имя-регистра.под-поле=значение</para></listitem> + <listitem><para>набор-регистров.имя-регистра=значение</para></listitem> + <listitem><para>имя-регистра-цпу.под-поле=значение</para></listitem> + <listitem><para>имя-регистра-цпу=значение</para></listitem> + </orderedlist> + <para>Форматр значений должен быть в том же стиле, в каком отображаются + по команде <command>getregisters</command>, за исключением того, что + могут быть указаны восмеричные и десятичные значения вместо + шестнадцатиричных.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--cpu=<replaceable>id</replaceable></option></term> + <listitem><para>Выбирает набор регистров ЦПУ при указании только + регистра ЦПУ (3-я и 4-я формы). По умолчанию 0.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-show"> + <title>debugvm show</title> + <remark role="help-copy-synopsis"/> + <para> + Отображает настройки журнала для ВМ. + </para> + <variablelist> + <varlistentry> + <term><option>--human-readable</option></term> + <listitem><para>Выбирает человеко-читаемый вывод.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--sh-export</option></term> + <listitem><para>Выбирает формат вывода в стиле bourne shell команды <command>export</command>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--sh-eval</option></term> + <listitem><para>Выбирает формат вывода в стиле аргументов bourne shell команды <command>eval</command>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cmd-set</option></term> + <listitem><para>Выбирает формат вывода в стиле команды DOS <command>SET</command>.</para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>settings-item</replaceable></term> + <listitem> + <para>Указывает что отображать. Один или несколько из следующих:</para> + <itemizedlist> + <listitem><para>logdbg-settings - настройки журнала в режиме отладки.</para></listitem> + <listitem><para>logrel-settings - настройки журнала в режиме выпуска.</para></listitem> + <listitem><para>log-settings - псевдоним для настроек журнала в режимах и отладки и выпуска.</para></listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="vboxmanage-debugvm-stack"> + <title>debugvm stack</title> + <remark role="help-copy-synopsis"/> + <para> + Разматывает стеки гостевого ЦПУ в меру наших возможностей. Рекомендуется + сначала запустить команду <command>osdetect</command> чтобы получить + символы и возможно информацию для раскрутки стека. + </para> + <variablelist> + <varlistentry> + <term><option>--cpu=<replaceable>id</replaceable></option></term> + <listitem><para>Выбирает один гостевой ЦПУ, у которого надо отобразить стек. По умолчанию все ЦПУ.</para> </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="vboxmanage-debugvm-statistics"> + <title>debugvm statistics</title> + <remark role="help-copy-synopsis"/> + <para> + Отображает или сбрасывает статистики VMM. + </para> + <para> + Получает значения регистров для гостевых ЦПУ и эмулируемых устройств. + </para> + <variablelist> + <varlistentry> + <term><option>--pattern=<replaceable>шаблон</replaceable></option></term> + <listitem><para>Шаблоны с подстановочными знаками в стиле DOS/NT для выбранных статистик. + Множественные шаблоны указываются через символ '|' (канал) в качестве разделителя.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--reset</option></term> + <listitem><para>Выбрать сброс вместо режима отображения.</para></listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="vboxmanage-debugvm-guestsample"> + <title>debugvm guestsample</title> + <remark role="help-copy-synopsis"/> + <para> + Создает отчет с выборками о гостевой активности. + </para> + <para> + Получает имя файла куда сбрасывать отчет. + </para> + <variablelist> + <varlistentry> + <term><option>--filename=<replaceable>имя-файла</replaceable></option></term> + <listitem><para>Имя файла куда сбрасывать отчет с выборками.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--sample-interval-us=<replaceable>интервал</replaceable></option></term> + <listitem><para>Интервал в микросекундах между гостевыми выборками.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--sample-time-us=<replaceable>time</replaceable></option></term> + <listitem><para>Количество микросекунд, в течение которых берется выборка.</para> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + </refsect1> + +</refentry> + diff --git a/doc/manual/ru_RU/man_VBoxManage-dhcpserver-dhcpoptions.xml b/doc/manual/ru_RU/man_VBoxManage-dhcpserver-dhcpoptions.xml new file mode 100644 index 00000000..d368c964 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-dhcpserver-dhcpoptions.xml @@ -0,0 +1,231 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Manually generated from src/VBox/Main/idl/VirtualBox.xidl by 'kmk dhcpoptions'. + DO NOT EDIT! +--> +<!-- + Copyright (C) 2019-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + + <variablelist> + <varlistentry> + <term>1 - SubnetMask</term> + <listitem><para>IPv4 netmask. Set to the value of the --netmask option by default.</para></listitem> + </varlistentry> <varlistentry> + <term>2 - TimeOffset</term> + <listitem><para>UTC offset in seconds (32-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>3 - Routers</term> + <listitem><para>Space separated list of IPv4 router addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>4 - TimeServers</term> + <listitem><para>Space separated list of IPv4 time server (RFC 868) addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>5 - NameServers</term> + <listitem><para>Space separated list of IPv4 name server (IEN 116) addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>6 - DomainNameServers</term> + <listitem><para>Space separated list of IPv4 DNS addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>7 - LogServers</term> + <listitem><para>Space separated list of IPv4 log server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>8 - CookieServers</term> + <listitem><para>Space separated list of IPv4 cookie server (RFC 865) addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>9 - LPRServers</term> + <listitem><para>Space separated list of IPv4 line printer server (RFC 1179) addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>10 - ImpressServers</term> + <listitem><para>Space separated list of IPv4 imagen impress server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>11 - ResourseLocationServers</term> + <listitem><para>Space separated list of IPv4 resource location (RFC 887) addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>12 - HostName</term> + <listitem><para>The client name. See RFC 1035 for character limits. </para></listitem> + </varlistentry> <varlistentry> + <term>13 - BootFileSize</term> + <listitem><para>Number of 512 byte blocks making up the boot file (16-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>14 - MeritDumpFile</term> + <listitem><para>Client core file.</para></listitem> + </varlistentry> <varlistentry> + <term>15 - DomainName</term> + <listitem><para>Domain name for the client.</para></listitem> + </varlistentry> <varlistentry> + <term>16 - SwapServer</term> + <listitem><para>IPv4 address of the swap server that the client should use.</para></listitem> + </varlistentry> <varlistentry> + <term>17 - RootPath</term> + <listitem><para>The path to the root disk the client should use.</para></listitem> + </varlistentry> <varlistentry> + <term>18 - ExtensionPath</term> + <listitem><para>Path to a file containing additional DHCP options (RFC2123).</para></listitem> + </varlistentry> <varlistentry> + <term>19 - IPForwarding</term> + <listitem><para>Whether IP forwarding should be enabled by the client (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>20 - OptNonLocalSourceRouting</term> + <listitem><para>Whether non-local datagrams should be forwarded by the client (boolean)</para></listitem> + </varlistentry> <varlistentry> + <term>21 - PolicyFilter</term> + <listitem><para>List of IPv4 addresses and masks paris controlling non-local source routing.</para></listitem> + </varlistentry> <varlistentry> + <term>22 - MaxDgramReassemblySize</term> + <listitem><para>The maximum datagram size the client should reassemble (16-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>23 - DefaultIPTTL</term> + <listitem><para>The default time-to-leave on outgoing (IP) datagrams (8-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>24 - PathMTUAgingTimeout</term> + <listitem><para>RFC1191 path MTU discovery timeout value in seconds (32-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>25 - PathMTUPlateauTable</term> + <listitem><para>RFC1191 path MTU discovery size table, sorted in ascending order (list of 16-bit decimal values).</para></listitem> + </varlistentry> <varlistentry> + <term>26 - InterfaceMTU</term> + <listitem><para>The MTU size for the interface (16-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>27 - AllSubnetsAreLocal</term> + <listitem><para>Indicates whether the MTU size is the same for all subnets (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>28 - BroadcastAddress</term> + <listitem><para>Broadcast address (RFC1122) for the client to use (IPv4 address).</para></listitem> + </varlistentry> <varlistentry> + <term>29 - PerformMaskDiscovery</term> + <listitem><para>Whether to perform subnet mask discovery via ICMP (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>30 - MaskSupplier</term> + <listitem><para>Whether to respond to subnet mask requests via ICMP (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>31 - PerformRouterDiscovery</term> + <listitem><para>Whether to perform router discovery (RFC1256) (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>32 - RouterSolicitationAddress</term> + <listitem><para>Where to send router solicitation requests (RFC1256) (IPv4 address).</para></listitem> + </varlistentry> <varlistentry> + <term>33 - StaticRoute</term> + <listitem><para>List of network and router address pairs addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>34 - TrailerEncapsulation</term> + <listitem><para>Whether to negotiate the use of trailers for ARP (RTF893) (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>35 - ARPCacheTimeout</term> + <listitem><para>The timeout in seconds for ARP cache entries (32-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>36 - EthernetEncapsulation</term> + <listitem><para>Whether to use IEEE 802.3 (RTF1042) rather than of v2 (RFC894) ethernet encapsulation (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>37 - TCPDefaultTTL</term> + <listitem><para>Default time-to-live for TCP sends (non-zero 8-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>38 - TCPKeepaliveInterval</term> + <listitem><para>The interface in seconds between TCP keepalive messages (32-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>39 - TCPKeepaliveGarbage</term> + <listitem><para>Whether to include a byte of garbage in TCP keepalive messages for backward compatibility (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>40 - NISDomain</term> + <listitem><para>The NIS (Sun Network Information Services) domain name (string).</para></listitem> + </varlistentry> <varlistentry> + <term>41 - NISServers</term> + <listitem><para>Space separated list of IPv4 NIS server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>42 - NTPServers</term> + <listitem><para>Space separated list of IPv4 NTP (RFC1035) server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>43 - VendorSpecificInfo</term> + <listitem><para>Vendor specific information. Only accessible using --set-opt-hex.</para></listitem> + </varlistentry> <varlistentry> + <term>44 - NetBIOSNameServers</term> + <listitem><para>Space separated list of IPv4 NetBIOS name server (NBNS) addresses (RFC1001,RFC1002).</para></listitem> + </varlistentry> <varlistentry> + <term>45 - NetBIOSDatagramServers</term> + <listitem><para>Space separated list of IPv4 NetBIOS datagram distribution server (NBDD) addresses (RFC1001,RFC1002).</para></listitem> + </varlistentry> <varlistentry> + <term>46 - NetBIOSNodeType</term> + <listitem><para>NetBIOS node type (RFC1001,RFC1002): 1=B-node, 2=P-node, 4=M-node, and 8=H-node (8-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>47 - NetBIOSScope</term> + <listitem><para>NetBIOS scope (RFC1001,RFC1002). Only accessible using --set-opt-hex.</para></listitem> + </varlistentry> <varlistentry> + <term>48 - XWindowsFontServers</term> + <listitem><para>Space separated list of IPv4 X windows font server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>49 - XWindowsDisplayManager</term> + <listitem><para>Space separated list of IPv4 X windows display manager addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>62 - NetWareIPDomainName</term> + <listitem><para>Netware IP domain name (RFC2242) (string).</para></listitem> + </varlistentry> <varlistentry> + <term>63 - NetWareIPInformation</term> + <listitem><para>Netware IP information (RFC2242). Only accessible using --set-opt-hex.</para></listitem> + </varlistentry> <varlistentry> + <term>64 - NISPlusDomain</term> + <listitem><para>The NIS+ domain name (string).</para></listitem> + </varlistentry> <varlistentry> + <term>65 - NISPlusServers</term> + <listitem><para>Space separated list of IPv4 NIS+ server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>66 - TFTPServerName</term> + <listitem><para>TFTP server name (string).</para></listitem> + </varlistentry> <varlistentry> + <term>67 - BootfileName</term> + <listitem><para>Bootfile name (string).</para></listitem> + </varlistentry> <varlistentry> + <term>68 - MobileIPHomeAgents</term> + <listitem><para>Space separated list of IPv4 mobile IP agent addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>69 - SMTPServers</term> + <listitem><para>Space separated list of IPv4 simple mail transport protocol (SMPT) server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>70 - POP3Servers</term> + <listitem><para>Space separated list of IPv4 post office protocol 3 (POP3) server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>71 - NNTPServers</term> + <listitem><para>Space separated list of IPv4 network news transport protocol (NTTP) server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>72 - WWWServers</term> + <listitem><para>Space separated list of default IPv4 world wide web (WWW) server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>73 - FingerServers</term> + <listitem><para>Space separated list of default IPv4 finger server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>74 - IRCServers</term> + <listitem><para>Space separated list of default IPv4 internet relay chat (IRC) server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>75 - StreetTalkServers</term> + <listitem><para>Space separated list of IPv4 StreetTalk server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>76 - STDAServers</term> + <listitem><para>Space separated list of IPv4 StreetTalk directory assistance (STDA) server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>78 - SLPDirectoryAgent</term> + <listitem><para>Addresses of one or more service location protocol (SLP) directory agent, and an indicator of whether their use is mandatory. Only accessible using --set-opt-hex.</para></listitem> + </varlistentry> <varlistentry> + <term>79 - SLPServiceScope</term> + <listitem><para>List of service scopes for the service location protocol (SLP) and whether using the list is mandator. Only accessible using --set-opt-hex.</para></listitem> + </varlistentry> <varlistentry> + <term>119 - DomainSearch</term> + <listitem><para>Domain search list, see RFC3397 and section 4.1.4 in RFC1035 for encoding. Only accessible using --set-opt-hex.</para></listitem> + </varlistentry> + </variablelist> diff --git a/doc/manual/ru_RU/man_VBoxManage-dhcpserver.xml b/doc/manual/ru_RU/man_VBoxManage-dhcpserver.xml new file mode 100644 index 00000000..117c7b6c --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-dhcpserver.xml @@ -0,0 +1,611 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage dhcpserver +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-dhcpserver" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage dhcpserver</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-dhcpserver</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-dhcpserver</refname> + <refpurpose>Управление DHCP сервером</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-add"> + <command>VBoxManage dhcpserver add</command> + <group choice="req"> + <arg choice="plain">--network=<replaceable>имя-сети</replaceable></arg> + <arg choice="plain">--interface=<replaceable>имя-интерфейса</replaceable></arg> + </group> + <arg choice="req">--server-ip=<replaceable>адрес</replaceable></arg> + <arg choice="req">--netmask=<replaceable>маска</replaceable></arg> + <arg choice="req">--lower-ip=<replaceable>адрес</replaceable></arg> + <arg choice="req">--upper-ip=<replaceable>адрес</replaceable></arg> + <group choice="req"> + <arg choice="plain">--enable</arg> + <arg choice="plain">--disable</arg> + </group> + <sbr/> + <group rep="repeat"> + <arg>--global</arg> + <arg rep="repeat">--set-opt=<replaceable>номер-опции-dhcp значение</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>номер-опции-dhcp строка-hex</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg>--min-lease-time=<replaceable>секунды</replaceable></arg> + <arg>--default-lease-time=<replaceable>секунды</replaceable></arg> + <arg>--max-lease-time=<replaceable>секунды</replaceable></arg> + </group> + <sbr/> + <group rep="repeat"> + <arg choice="req">--group=<replaceable>имя</replaceable></arg> + <arg rep="repeat">--set-opt=<replaceable>номер-опции-dhcp значение</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>номер-опции-dhcp строка-hex</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg rep="repeat">--incl-mac=<replaceable>адрес</replaceable></arg> + <arg rep="repeat">--excl-mac=<replaceable>адрес</replaceable></arg> + <arg rep="repeat">--incl-mac-wild=<replaceable>шаблон</replaceable></arg> + <arg rep="repeat">--excl-mac-wild=<replaceable>шаблон</replaceable></arg> + <arg rep="repeat">--incl-vendor=<replaceable>строка</replaceable></arg> + <arg rep="repeat">--excl-vendor=<replaceable>строка</replaceable></arg> + <arg rep="repeat">--incl-vendor-wild=<replaceable>шаблон</replaceable></arg> + <arg rep="repeat">--excl-vendor-wild=<replaceable>шаблон</replaceable></arg> + <arg rep="repeat">--incl-user=<replaceable>строка</replaceable></arg> + <arg rep="repeat">--excl-user=<replaceable>строка</replaceable></arg> + <arg rep="repeat">--incl-user-wild=<replaceable>шаблон</replaceable></arg> + <arg rep="repeat">--excl-user-wild=<replaceable>шаблон</replaceable></arg> + <arg>--min-lease-time=<replaceable>секунды</replaceable></arg> + <arg>--default-lease-time=<replaceable>секунды</replaceable></arg> + <arg>--max-lease-time=<replaceable>секунды</replaceable></arg> + </group> + <sbr/> + <group rep="repeat"> + <arg choice="req">--vm=<replaceable>имя|uuid</replaceable></arg> + <arg>--nic=<replaceable>1-N</replaceable></arg> + <arg rep="repeat">--set-opt=<replaceable>номер-опции-dhcp значение</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>номер-опции-dhcp строка-hex</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg>--min-lease-time=<replaceable>секунды</replaceable></arg> + <arg>--default-lease-time=<replaceable>секунды</replaceable></arg> + <arg>--max-lease-time=<replaceable>секунды</replaceable></arg> + <arg>--fixed-address=<replaceable>адрес</replaceable></arg> + </group> + <sbr/> + <group rep="repeat"> + <arg choice="req">--mac-address=<replaceable>адрес</replaceable></arg> + <arg rep="repeat">--set-opt=<replaceable>номер-опции-dhcp значение</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>номер-опции-dhcp строка-hex</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg>--min-lease-time=<replaceable>секунды</replaceable></arg> + <arg>--default-lease-time=<replaceable>секунды</replaceable></arg> + <arg>--max-lease-time=<replaceable>секунды</replaceable></arg> + <arg>--fixed-address=<replaceable>адрес</replaceable></arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-modify"> + <command>VBoxManage dhcpserver modify</command> + <group choice="req"> + <arg choice="plain">--network=<replaceable>имя-сети</replaceable></arg> + <arg choice="plain">--interface=<replaceable>имя-интерфейса</replaceable></arg> + </group> + <arg>--server-ip=<replaceable>адрес</replaceable></arg> + <arg>--lower-ip=<replaceable>адрес</replaceable></arg> + <arg>--upper-ip=<replaceable>адрес</replaceable></arg> + <arg>--netmask=<replaceable>маска</replaceable></arg> + <group> + <arg choice="plain">--enable</arg> + <arg choice="plain">--disable</arg> + </group> + <sbr/> + <group rep="repeat"> + <arg>--global</arg> + <arg rep="repeat">--del-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg rep="repeat">--set-opt=<replaceable>номер-опции-dhcp значение</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>номер-опции-dhcp значение</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg rep="repeat">--unforce-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg rep="repeat">--unsupress-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg>--min-lease-time=<replaceable>секунды</replaceable></arg> + <arg>--default-lease-time=<replaceable>секунды</replaceable></arg> + <arg>--max-lease-time=<replaceable>секунды</replaceable></arg> + <arg>--remove-config</arg> + </group> + <sbr/> + <group rep="repeat"> + <arg choice="req">--group=<replaceable>имя</replaceable></arg> + <arg rep="repeat">--set-opt=<replaceable>номер-опции-dhcp значение</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>номер-опции-dhcp строка-hex</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg rep="repeat">--unforce-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg rep="repeat">--unsupress-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg rep="repeat">--del-mac=<replaceable>адрес</replaceable></arg> + <arg rep="repeat">--incl-mac=<replaceable>адрес</replaceable></arg> + <arg rep="repeat">--excl-mac=<replaceable>адрес</replaceable></arg> + <arg rep="repeat">--del-mac-wild=<replaceable>шаблон</replaceable></arg> + <arg rep="repeat">--incl-mac-wild=<replaceable>шаблон</replaceable></arg> + <arg rep="repeat">--excl-mac-wild=<replaceable>шаблон</replaceable></arg> + <arg rep="repeat">--del-vendor=<replaceable>строка</replaceable></arg> + <arg rep="repeat">--incl-vendor=<replaceable>строка</replaceable></arg> + <arg rep="repeat">--excl-vendor=<replaceable>строка</replaceable></arg> + <arg rep="repeat">--del-vendor-wild=<replaceable>шаблон</replaceable></arg> + <arg rep="repeat">--incl-vendor-wild=<replaceable>шаблон</replaceable></arg> + <arg rep="repeat">--excl-vendor-wild=<replaceable>шаблон</replaceable></arg> + <arg rep="repeat">--del-user=<replaceable>строка</replaceable></arg> + <arg rep="repeat">--incl-user=<replaceable>строка</replaceable></arg> + <arg rep="repeat">--excl-user=<replaceable>строка</replaceable></arg> + <arg rep="repeat">--del-user-wild=<replaceable>шаблон</replaceable></arg> + <arg rep="repeat">--incl-user-wild=<replaceable>шаблон</replaceable></arg> + <arg rep="repeat">--excl-user-wild=<replaceable>шаблон</replaceable></arg> + <arg>--zap-conditions</arg> + <arg>--min-lease-time=<replaceable>секунды</replaceable></arg> + <arg>--default-lease-time=<replaceable>секунды</replaceable></arg> + <arg>--max-lease-time=<replaceable>секунды</replaceable></arg> + <arg>--remove-config</arg> + </group> + <sbr/> + <group rep="repeat"> + <arg choice="req">--vm=<replaceable>имя|uuid</replaceable></arg> + <arg>--nic=<replaceable>1-N</replaceable></arg> + <arg rep="repeat">--del-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg rep="repeat">--set-opt=<replaceable>номер-опции-dhcp значение</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>номер-опции-dhcp строка-hex</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg rep="repeat">--unforce-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg rep="repeat">--unsupress-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg>--min-lease-time=<replaceable>секунды</replaceable></arg> + <arg>--default-lease-time=<replaceable>секунды</replaceable></arg> + <arg>--max-lease-time=<replaceable>секунды</replaceable></arg> + <arg>--fixed-address=<replaceable>адрес</replaceable></arg> + <arg>--remove-config</arg> + </group> + <sbr/> + <group rep="repeat"> + <arg choice="req">--mac-address=<replaceable>адрес</replaceable></arg> + <arg rep="repeat">--del-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg rep="repeat">--set-opt=<replaceable>номер-опции-dhcp значение</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>номер-опции-dhcp строка-hex</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg rep="repeat">--unforce-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg rep="repeat">--unsupress-opt=<replaceable>номер-опции-dhcp</replaceable></arg> + <arg>--min-lease-time=<replaceable>секунды</replaceable></arg> + <arg>--default-lease-time=<replaceable>секунды</replaceable></arg> + <arg>--max-lease-time=<replaceable>секунды</replaceable></arg> + <arg>--fixed-address=<replaceable>адрес</replaceable></arg> + <arg>--remove-config</arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-remove"> + <command>VBoxManage dhcpserver remove</command> + <group choice="req"> + <arg choice="plain">--network=<replaceable>имя-сети</replaceable></arg> + <arg choice="plain">--interface=<replaceable>имя-интерфейса</replaceable></arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-start"> + <command>VBoxManage dhcpserver start</command> + <group choice="req"> + <arg choice="plain">--network=<replaceable>имя-сети</replaceable></arg> + <arg choice="plain">--interface=<replaceable>имя-интерфейса</replaceable></arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-restart"> + <command>VBoxManage dhcpserver restart</command> + <group choice="req"> + <arg choice="plain">--network=<replaceable>имя-сети</replaceable></arg> + <arg choice="plain">--interface=<replaceable>имя-интерфейса</replaceable></arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-stop"> + <command>VBoxManage dhcpserver stop</command> + <group choice="req"> + <arg choice="plain">--network=<replaceable>имя-сети</replaceable></arg> + <arg choice="plain">--interface=<replaceable>имя-интерфейса</replaceable></arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-findlease"> + <command>VBoxManage dhcpserver findlease</command> + <group choice="req"> + <arg choice="plain">--network=<replaceable>имя-сети</replaceable></arg> + <arg choice="plain">--interface=<replaceable>имя-интерфейса</replaceable></arg> + </group> + <arg choice="req">--mac-address=<replaceable>mac</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + + <para> + Команды <command>dhcpserver</command> позволяют управлять встроенным в + VirtualBox DHCP сервером. Это может быть полезно при использовании + внутренней сети или сети хоста. Теоретически, его можно использовать + также и для сетевого моста, но это может вызвать конфликты с другими + DHCP серверами, находящимся в вашей физической сети. + </para> + + <refsect2 id="vboxmanage-dhcpserver-common-options"> + <title>Общие параметры</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>Все подкоманды <command>dhcpserver</command> работают во внутренней + сети, идентифицируемой через ее имя или, в случае с сетью хоста, через + имя интерфейса:</para> + <variablelist> + <varlistentry> + <term>--network=<replaceable>имя-сети</replaceable></term> + <listitem><para>Имя внутренней сети. Это то же самое имя, которое было + задано в опции <command>VBoxManage modifyvm --intnet</command> при + настройке ВМ на внутреннюю сеть. Также его можно посмотреть в поле + "Имя сети VBox" вывода команд + <command>VBoxManage list intnets</command>, + <command>VBoxManage list natnets</command> или + <command>VBoxManage list hostonlyifs</command>. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--interface=<replaceable>имя-интерфейса</replaceable></term> + <listitem><para>Имя интерфейса сети хоста. Это то же самое имя, которое + было задано в опции <command>VBoxManage modifyvm --host-only-adapter</command> + при настройке ВМ на сеть хоста. Оно также может быть получено в поле "Имя" + вывода команды <command>VBoxManage list hostonlyifs</command>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-add"> + <title>dhcpserver add</title> + <remark role="help-copy-synopsis"/> + <para> + Добавляет новый DHCP сервер в сеть или интерфейс сети хоста. + </para> + <para> + Опции для настройки ядра DHCP сервера: + </para> + <variablelist> + <varlistentry> + <term><option>--server-ip=<replaceable>адрес</replaceable></option></term> + <listitem><para>IP адрес, который должен быть у DHCP сервера.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--lower-ip=<replaceable>адрес</replaceable></option>, <option>--upper-ip=<replaceable>адрес</replaceable></option></term> + <listitem><para>Диапазон IP адресов в управлении у DHCP сервера. + Он не должен включать адрес самого DHCP сервера, но должен быть в + той же сети. Границы включены, так что и верхний и нижний адреса + также распределяются между клиентами.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--netmask=<replaceable>маска</replaceable></option></term> + <listitem><para>Сетевая маска. Обычно 255.255.255.0.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--enable</option>, --disable</term> + <listitem><para>Включает или выключает DHCP сервер. Если не указан, + сервер создается в выключенном состоянии и не распределяет адресов.</para></listitem> + </varlistentry> + </variablelist> + <para> + Опции, определяющие область настроек: + </para> + <variablelist> + <varlistentry> + <term><option>--global</option></term> + <listitem><para>Задать глобальную область настроек. Любые последующие опции + <option>--set-opt</option> будут применены ко всем клиентам DHCP.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vm=<replaceable>имя-ВМ|uuid</replaceable></option></term> + <listitem><para>Задать область настроек, ограниченную первым NIC указанной ВМ. + Любые последующие опции <option>--set-opt</option> будут применены только + к этому интерфейсу и никуда больше.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic=<replaceable>1-N</replaceable></option></term> + <listitem><para>Задать область настроек, ограниченную указанным номером интерфейса ВМ, + заданной через опцию <option>--vm</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mac-address=<replaceable>адрес</replaceable></option></term> + <listitem><para>Задать область настроек, ограниченную указанным MAC адресом.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--group=<replaceable>имя</replaceable></option></term> + <listitem><para>Задать область настроек, ограниченную указанной группой.</para></listitem> + </varlistentry> + </variablelist> + <para> + Опции для настройки текущей выбранной области: + </para> + <variablelist> + <varlistentry> + <term><option>--set-opt=<replaceable>номер-опции-dhcp значение</replaceable></option></term> + <listitem><para>Добавляет указанный номер опции DHCP (0-255) и значение. Формат значения + опции зависит от опции (обычно человеко-читаемый) и проверяется API и сервером DHCP. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--set-opt-hex=<replaceable>номер-опции-dhcp строка-hex</replaceable></option></term> + <listitem><para>Добавляет указанный номер опции DHCP (0-255) и значение. Значение параметра + задается в виде необработанной последовательности шестнадцатеричных байтов, которые могут + быть разделены двоеточием. Проверка этих значений не производится ни API, ни DHCP сервером, + они как есть передаются клиенту. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--force-opt=<replaceable>номер-опции-dhcp</replaceable></option></term> + <listitem><para>Принудительно отправляет указанный номер опции DHCP (0-255) клиенту + независимо от того, запрашивал он это или нет (при условии, что опция настроена + со значением на некотором уровне). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--suppress-opt=<replaceable>номер-опции-dhcp</replaceable></option></term> + <listitem><para> Предотвращает отправку клиенту указанного номера опции DHCP (0–255), + если он присутствует в этой или более высокой области настроек. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--min-lease-time=<replaceable>секунды</replaceable></option></term> + <listitem><para>Устанавливает минимальное время аренды для текущей области в секундах. + Ноль означает получение значения из более высокого уровня настроек или использование + значения по умолчанию. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--default-lease-time=<replaceable>секунды</replaceable></option></term> + <listitem><para>Задает время аренды по умолчанию для текущей области в секундах. Ноль + означает получение значения из более высокого уровня настроек или использование + значения по умолчанию. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--max-lease-time=<replaceable>секунды</replaceable></option></term> + <listitem><para>Устанавливает максимальное время аренды для текущей области в секундах. + Ноль означает получение значения из более высокого уровня настроек или использование + значения по умолчанию. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--fixed-address=<replaceable>адрес</replaceable></option></term> + <listitem><para>Назначение фиксированного адреса для области настроек + <option>--vm</option> или <option>--mac-address</option>. Пустой + <replaceable>адрес</replaceable> возвращает обратно назначение динамического + адреса. + </para></listitem> + </varlistentry> + </variablelist> + + <para> + Опции для настройки условий членства в группе (исключение, переопределение, включение): + </para> + <variablelist> + <varlistentry> + <term><option>--incl-mac=<replaceable>адрес</replaceable></option></term> + <listitem><para>Включает указанный MAC адрес в группу.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--excl-mac=<replaceable>адрес</replaceable></option></term> + <listitem><para>Исключает указанный MAC адрес из группы.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--incl-mac-wild=<replaceable>шаблон</replaceable></option></term> + <listitem><para>Включает указанный шаблон MAC адреса в группу.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--excl-mac-wild=<replaceable>шаблон</replaceable></option></term> + <listitem><para>Исключает указанный шаблон MAC адреса из группы.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--incl-vendor=<replaceable>строка</replaceable></option></term> + <listitem><para>Включает указанный ID класса поставщика в группу.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--excl-vendor=<replaceable>строка</replaceable></option></term> + <listitem><para>Исключает указанный ID класса поставщика из группы.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--incl-vendor-wild=<replaceable>шаблон</replaceable></option></term> + <listitem><para>Включает указанный шаблон ID класса поставщика в группу.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--excl-vendor-wild=<replaceable>шаблон</replaceable></option></term> + <listitem><para>Исключает указанный шаблон ID класса поставщика из группы.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--incl-user=<replaceable>строка</replaceable></option></term> + <listitem><para>Включает указанный ID класса пользователя в группу.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--excl-user=<replaceable>строка</replaceable></option></term> + <listitem><para>Исключает указанный ID класса пользователя из группы.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--incl-user-wild=<replaceable>шаблон</replaceable></option></term> + <listitem><para>Включает указанный шаблон ID класса пользователя в группу.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--excl-user-wild=<replaceable>шаблон</replaceable></option></term> + <listitem><para>Исключает указанный шаблон ID класса пользователя из группы.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-modify"> + <title>dhcpserver modify</title> + <remark role="help-copy-synopsis"/> + <para> + Команда модифицирует существующую конфигурацию сервера DHCP. Она принимает те же + опции как и команда <command>add</command> и в дополнении нижеследующие, относящиеся + к области настроек: + </para> + <variablelist> + <varlistentry> + <term><option>--del-opt=<replaceable>номер-опции-dhcp</replaceable></option></term> + <listitem><para>Противоположность к <option>--set-opt</option>, которая удаляет + указанный номер опции DHCP (0-255) из настроек сервера. Как и у + <option>--set-opt</option>, область удаления регулируется опциями + <option>--global</option>, <option>--vm</option>, <option>--mac-address</option> + и <option>--group</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unforce-opt=<replaceable>номер-опции-dhcp</replaceable></option></term> + <listitem><para>Удаляет указанный номер опции DHCP (0-255) из списка принудительно + передаваемых клиенту опций (то есть обратная к <option>--force-opt</option>). Как и у + <option>--set-opt</option>, область удаления регулируется опциями + <option>--global</option>, <option>--vm</option>, <option>--mac-address</option> + и <option>--group</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unsuppress-opt=<replaceable>номер-опции-dhcp</replaceable></option></term> + <listitem><para>Удаляет указанный номер DHCP (0-255) из списка опций для подавления + передачи клиенту (то есть обратная к <option>--suppress-opt</option>). Как и у + <option>--set-opt</option>, область удаления регулируется опциями + <option>--global</option>, <option>--vm</option>, <option>--mac-address</option> + и <option>--group</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--remove-config</option></term> + <listitem><para>Удаляет настройки из текущей области. Область <option>--global</option> + нельзя удалить. После этой опции область настроек будет изменена на + <option>--global</option>. + </para></listitem> + </varlistentry> + </variablelist> + <para> + И дополнение к опциям условий членства в группах: + </para> + <variablelist> + <varlistentry> + <term><option>--del-mac=<replaceable>адрес</replaceable></option></term> + <listitem><para>Удаляет указанный MAC адрес из условий группы.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--del-mac-wild=<replaceable>шаблон</replaceable></option></term> + <listitem><para>Удаляет указанный шаблон MAC адреса из условий группы.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--del-vendor=<replaceable>строка</replaceable></option></term> + <listitem><para>Удаляет указанный ID класса поставщика из условий группы.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--del-vendor-wild=<replaceable>шаблон</replaceable></option></term> + <listitem><para>Удаляет указанный шаблон ID класса поставщика из условий группы.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--del-user=<replaceable>строка</replaceable></option></term> + <listitem><para>Удаляет указанный ID класса пользователя из условий группы.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--del-user-wild=<replaceable>pattern</replaceable></option></term> + <listitem><para>Удаляет указанный шаблон ID класса пользователя из условий группы.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--zap-conditions</option></term> + <listitem><para>Удаляет все условия группы.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-remove"> + <title>dhcpserver remove</title> + <remark role="help-copy-synopsis"/> + <para> + Удаляет указанный сервер DHCP. + </para> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-start"> + <title>dhcpserver start</title> + <remark role="help-copy-synopsis"/> + <para> + Запускает указанный сервер DHCP. + </para> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-restart"> + <title>dhcpserver restart</title> + <remark role="help-copy-synopsis"/> + <para> + Перезапускает указанный сервер DHCP. Сервер DHCP должен работать на момент запуска команды. + </para> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-stop"> + <title>dhcpserver stop</title> + <remark role="help-copy-synopsis"/> + <para> + Останавливает указанный сервер DHCP. + </para> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-findlease"> + <title>dhcpserver findlease</title> + <remark role="help-copy-synopsis"/> + <para> + Производит просмотр базы данных аренды. Эта команда в основном + для получения IP адреса работающей ВМ. + </para> + <variablelist> + <varlistentry> + <term><option>--mac-address=<replaceable>mac</replaceable></option></term> + <listitem><para>MAC адрес для просмотра в базе данных аренды.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-dhcpoptions"> + <title>Общие параметры DHCP:</title> + <remark role="help-scope" condition="DHCPSERVER_ADD|DHCPSERVER_MODIFY"/> + <!-- The following file is generated from src/VBox/Main/idl/VirtualBox.xidl: --> + <xi:include href="man_VBoxManage-dhcpserver-dhcpoptions.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> + </refsect2> + + </refsect1> + +</refentry> + diff --git a/doc/manual/ru_RU/man_VBoxManage-discardstate.xml b/doc/manual/ru_RU/man_VBoxManage-discardstate.xml new file mode 100644 index 00000000..3c793f32 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-discardstate.xml @@ -0,0 +1,101 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage discardstate +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-discardstate" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage discardstate</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-discardstate</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-discardstate</refname> + <refpurpose>удаление сохраненного состояния виртуальной машины</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-discardstate"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage discardstate</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage discardstate</command> удаляет + сохраненное состояние виртуальной машины (ВМ) если она не + работает на текущий момент. Эта операция заставляет + операционную систему ВМ перезагрузиться при следующем старте ВМ. + </para> + <note> + <para> + Где возможно, избегайте этого действия. Эффект от этой команды + равносилен отсоединению кабеля питания из физической машины. + </para> + </note> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>имя-ВМ</replaceable></term> + <listitem><para> + Указывает Универсальный Уникальный Идентификатор (UUID) или + имя ВМ. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда удаляет файл сохраненного состояния ВМ, + называемой <filename>vm2</filename>. Когда в следующий раз + вы запустите ВМ, операционная система ВМ будет перезагружена. + </para> +<screen>$ VBoxManage discardstate vm2</screen> + </refsect1> + + <refsect1> + <title>Смотрите также</title> + <para> + <xref linkend="vboxmanage-adoptstate"/> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-encryptmedium.xml b/doc/manual/ru_RU/man_VBoxManage-encryptmedium.xml new file mode 100644 index 00000000..869935d1 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-encryptmedium.xml @@ -0,0 +1,169 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage encryptmedium +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-encryptmedium" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage encryptmedium</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-encryptmedium</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-encryptmedium</refname> + <refpurpose>управляет образом или носителем, зашифрованными DEK</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-encryptmedium"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage encryptmedium</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-файла</replaceable></arg> + </group> + <arg>--cipher=<replaceable>ID-шифра</replaceable></arg> + <arg>--newpassword=<replaceable>пароль</replaceable></arg> + <arg>--newpasswordid=<replaceable>ID-пароля</replaceable></arg> + <arg>--oldpassword=<replaceable>пароль</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage encryptmedium</command> позволяет + создавать или управлять образом или носителем, зашифрованными DEK. + Можно зашифровать образ, расшифровать образ, изменить пароль + шифрования образа. Смотрите <xref linkend="diskencryption-encryption" />. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>имя-файла</replaceable></term> + <listitem><para> + Задает Универсальный Уникальный Идентификатор (UUID) или + абсолютный путь шифруемого носителя или образа. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--newpassword=<replaceable>пароль</replaceable></option></term> + <listitem><para> + Задает новый пароль шифрования. <replaceable>пароль</replaceable> + - это или абсолютный путь к файлу с паролем в хост-системе + или <literal>-</literal>. Во втором случае будет предложено + ввести пароль. + </para><para> + Необходимо использовать опцию <option>--newpasswordid</option> + вместе с этой опцией <option>--newpassword</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--oldpassword=<replaceable>пароль</replaceable></option></term> + <listitem><para> + Задает исходный пароль шифрования. <replaceable>пароль</replaceable> + - это или абсолютный путь к файлу с паролем в хост-системе + или <literal>-</literal>. Во втором случае будет предложено + ввести пароль. + </para><para> + Эта опция позволяет получить доступ к зашифрованному + носителю или образу, чтобы произвести следующее: + </para><itemizedlist> + <listitem><para> + Расшифровать зашифрованный образ используя эту опцию. + </para></listitem> + <listitem><para> + Изменить пароль зашифрованного образа используя опцию + <option>--newpassword</option>. + </para></listitem> + <listitem><para> + Изменить шифр образа используя опцию + <option>--cipher</option>. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--cipher=<replaceable>ID-шифра</replaceable></option></term> + <listitem><para> + Указывает шифр для шифрования. Допустимые значения + <literal>AES-XTS128-PLAIN64</literal> или + <literal>AES-XTS256-PLAIN64</literal>. + </para><para> + Эта опция позволяет установить или изменить шифрование + носителя или образа. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--newpasswordid=<replaceable>ID-пароля</replaceable></option></term> + <listitem><para> + Указывает новый идентификатор пароля, используемого для + корректной идентификации, когда передаются несколько паролей + во время старта ВМ. + </para><para> + Если вы используете одни и те же пароль и идентификатор + пароля при шифровании нескольких образов то вам достаточно + указать пароль один раз во время старта ВМ. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + Следующий пример показывает как зашифровать образ + <filename>ol7u4-1.vdi</filename>, используя шифр + <literal>AES-XTS128-PLAIN64</literal>, задавая идентификатор + пароля <literal>1001</literal> и используя файл пароля + <filename>$HOME/pwfile</filename>: + </para> +<screen>$ VBoxManage encryptmedium "$HOME/VirtualBox VMs/ol7u4/ol7u4-1.vdi" \ + --cipher="AES-XTS128-PLAIN64" --newpasswordid="1001" --newpassword=$HOME/pwfile</screen> + <para> + Следующий пример показывает как расшифровать зашифрованный образ + называемый <filename>ol7u4-2.vdi</filename>: + </para> +<screen>$ VBoxManage encryptmedium "$HOME/VirtualBox VMs/ol7u4/ol7u4-2.vdi" \ + --oldpassword=- + Пароль: <replaceable>исходный-пароль</replaceable></screen> + <para> + Следующий пример показывает как изменить пароль зашифрованного + образа называемого <filename>ol7u4-3.vdi</filename>. Команда + читает исходный пароль из файла <filename>$HOME/pwfile.orig</filename> + и назначает идентификатор пароля <literal>1001</literal>. + </para> +<screen>$ VBoxManage encryptmedium "$HOME/VirtualBox VMs/ol7u4/ol7u4-3.vdi" \ + --oldpassword=$HOME/pwfile.orig --newpassword=$HOME/pwfile --newpasswordid="1001"</screen> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-encryptvm.xml b/doc/manual/ru_RU/man_VBoxManage-encryptvm.xml new file mode 100644 index 00000000..2e2c8673 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-encryptvm.xml @@ -0,0 +1,199 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage encryptvm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-encryptvm" lang="en"> + <refentryinfo> + <pubdate>May 2021</pubdate> + <title>VBoxManage encryptvm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-encryptvm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-encryptvm</refname> + <refpurpose>изменение шифрования и паролей ВМ</refpurpose> + <refclass>Oracle VM VirtualBox</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-encryptvm-setencryption"> + <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage encryptvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">setencryption</arg> + <arg choice="plain">--old-password <replaceable>файл</replaceable></arg> + <arg choice="plain">--cipher <replaceable>идентификатор-шифра</replaceable></arg> + <arg choice="plain">--new-password <replaceable>файл</replaceable></arg> + <arg choice="plain">--new-password-id <replaceable>идентификатор-пароля</replaceable></arg> + <arg choice="plain">--force</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-encryptvm-checkpassword"> + <command>VBoxManage encryptvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">checkpassword</arg> + <arg choice="req"><replaceable>файл</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-encryptvm-addpassword"> + <command>VBoxManage encryptvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">addpassword</arg> + <arg choice="plain">--password <replaceable>файл</replaceable></arg> + <arg choice="plain">--password-id <replaceable>идентификатор-пароля</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-encryptvm-removepassword"> + <command>VBoxManage encryptvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">removepassword</arg> + <arg choice="req"><replaceable>идентификатор-пароля</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage encryptvm</command> позволяет изменить + шифрование или добавить и удалить пароли пользователя виртуальной + машины (ВМ). Далее идут секции, описывающие поддерживаемые подкоманды: + </para> + <refsect2 id="vboxmanage-encryptvm-setencryption"> + <title>Задать шифрование виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage encryptvm + <replaceable>имя-ВМ</replaceable> setencryption</command> + изменяет шифрование ВМ. + </para> + <para> + Опция <option>--old-password</option> задает старый пароль + шифрования. Укажите абсолютный путь к файлу с паролем в + операционной системе хоста или <literal>-</literal>. Во втором + случае будет предложено ввести пароль. + </para> + <para> + Опция <option>--cipher</option> задает новый шифр для + шифрования ВМ. + </para> + <para> + Опция <option>--new-password</option> задает новый пароль + шифрования ВМ. Укажите абсолютный путь к файлу с паролем в + операционной системе хоста или <literal>-</literal>. Во втором + случае будет предложено ввести пароль. + </para> + <para> + Опция <option>--new-password-id</option> задает идентификатор + нового пароля шифрования ВМ. + </para> + <para> + Опция <option>--force</option> заставляет систему принудительно + перешифровать ВМ вместо простой смены пароля. + </para> + </refsect2> + <refsect2 id="vboxmanage-encryptvm-checkpassword"> + <title>Проверить заданный пароль на корректность</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage encryptvm + <replaceable>имя-ВМ</replaceable> checkpassword</command> проверяет + корректность указанного пароля. + </para> + <para> + Пароль может передан через файл. Укажите абсолютный путь к файлу + с паролем в операционной системе хоста или <literal>-</literal>. + Во втором случае будет предложено ввести пароль. + </para> + </refsect2> + <refsect2 id="vboxmanage-encryptvm-addpassword"> + <title>Добавить пароль для расшифровки виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage encryptvm + <replaceable>имя-ВМ</replaceable> addpassword</command> добавляет + пароль для расшифровки ВМ. + </para> + <para> + Опция <option>--password</option> задает пароль шифрования. + Укажите абсолютный путь к файлу с паролем в операционной + системе хоста или <literal>-</literal>. Во втором случае будет + предложено ввести пароль. + </para> + <para> + Опция <option>--password-id</option> задает id указанного пароля. + </para> + </refsect2> + <refsect2 id="vboxmanage-encryptvm-removepassword"> + <title>Отозвать пароль для расшифровки виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage encryptvm + <replaceable>имя-ВМ</replaceable> removepassword</command> отзывает + пароль для расшифровки ВМ. + </para> + <para> + Укажите идентификатор отзываемого пароля. Пароль становится + неизвестным и ВМ не может быть расшифрована. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда шифрует ВМ <filename>ol7</filename> с помощью + AES-256 получая пароль через приглашение командной строки: + </para> +<screen>$ VBoxManage encryptvm ol7 setencryption --cipher=AES-256 --new-password - --new-password-id vmid</screen> + </refsect1> + + <refsect1> + <title>Смотрите также</title> + <para> + <xref linkend="vboxmanage-createvm" />, + </para> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-export.xml b/doc/manual/ru_RU/man_VBoxManage-export.xml new file mode 100644 index 00000000..3b3df38e --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-export.xml @@ -0,0 +1,438 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage export +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-export" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage export</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-export</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-export</refname> + <refpurpose>экспорт одной или нескольких виртуальных машин в виртуальную конфигурацию или в облачную службу</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-export-ovf"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage export</command> + <arg choice="req"><replaceable>машины</replaceable></arg> + <arg choice="req">--output=<replaceable>имя</replaceable></arg> + <group> + <arg choice="plain">--legacy09</arg> + <arg choice="plain">--ovf09</arg> + <arg choice="plain">--ovf10</arg> + <arg choice="plain">--ovf20</arg> + </group> + <arg>--manifest</arg> + <arg>--options=<group choice="plain" rep="repeat"> + <arg choice="plain">manifest</arg> + <arg choice="plain">iso</arg> + <arg choice="plain">nomacs</arg> + <arg choice="plain">nomacsbutnat</arg> + </group></arg> + <arg>--vsys=<replaceable>номер-виртуальной-системы</replaceable></arg> + <arg>--description=<replaceable>описание</replaceable></arg> + <arg>--eula=<replaceable>текст-лицензии</replaceable></arg> + <arg>--eulafile=<replaceable>имя-файла</replaceable></arg> + <arg>--product=<replaceable>имя-продукта</replaceable></arg> + <arg>--producturl=<replaceable>URL-продукта</replaceable></arg> + <arg>--vendor=<replaceable>имя-поставщика</replaceable></arg> + <arg>--vendorurl=<replaceable>URL-поставщика</replaceable></arg> + <arg>--version=<replaceable>информация-о-версии</replaceable></arg> + <arg>--vmname=<replaceable>имя-ВМ</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-export-cloud"> + <command>VBoxManage export</command> + <arg choice="req"><replaceable>машина</replaceable></arg> + <arg choice="req">--output=<replaceable>провайдер-облачной-службы</replaceable></arg> + <arg>--opc10</arg> + <arg>--vmname=<replaceable>имя-ВМ</replaceable></arg> + <arg>--cloud=<replaceable>номер-виртуальной-системы</replaceable></arg> + <arg>--cloudprofile=<replaceable>имя-облачного-профиля</replaceable></arg> + <arg>--cloudshape=<replaceable>имя-облачной-формы</replaceable></arg> + <arg>--clouddomain=<replaceable>облачный-домен</replaceable></arg> + <arg>--clouddisksize=<replaceable>размер-диска-в-ГБ</replaceable></arg> + <arg>--cloudbucket=<replaceable>имя-корзины</replaceable></arg> + <arg>--cloudocivcn=<replaceable>OCI-VCN-ID</replaceable></arg> + <arg>--cloudocisubnet=<replaceable>ID-подсети-OCI</replaceable></arg> + <arg>--cloudkeepobject=<group choice="plain"> + <arg choice="plain">true</arg> + <arg choice="plain">false</arg> + </group></arg> + <arg>--cloudlaunchinstance=<group choice="plain"> + <arg choice="plain">true</arg> + <arg choice="plain">false</arg> + </group></arg> + <arg>--cloudlaunchmode=<group choice="plain"> + <arg choice="plain">EMULATED</arg> + <arg choice="plain">PARAVIRTUALIZED</arg> + </group></arg> + <arg>--cloudpublicip=<group choice="plain"> + <arg choice="plain">true</arg> + <arg choice="plain">false</arg> + </group></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage export</command> позволяет экспортировать + одну или несколько виртуальных машин (ВМ) из &product-name;. + Можно экспортировать ВМ в одно из следующих назначений: + </para> + <itemizedlist> + <listitem><para> + <emphasis role="bold">Виртуальная конфигурация в OVF формат.</emphasis> + Включает копирование ее виртуальных дисков в сжатый VMDK. + </para></listitem> + <listitem><para> + <emphasis role="bold">Облачная служба, например &oci;.</emphasis> + Экспортирует только одну машину VM. + </para></listitem> + </itemizedlist> + <para> + Для более детальной информации об экспорте ВМ из &product-name; + смотрите <xref linkend="ovf" /> + </para> + <refsect2 id="vboxmanage-export-ovf"> + <title>Экспорт виртуальной машины в виртуальную конфигурацию OVF</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage export</command> позволяет экспортировать + ВМ в виртуальную конфигурацию в формате OVF. + </para> + <variablelist> + <varlistentry> + <term><replaceable>машины</replaceable></term> + <listitem><para> + Задает список, разделенный запятыми, одной или нескольких + машин для экспорта в один файл OVF. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--output=<replaceable>имя-файла</replaceable></option></term> + <listitem><para> + Задает файл назначения OVF. Файл может быть OVF, OVA или + файл ZIP сжатый через команду <command>gzip</command>. + Из-за того, что директория, содержащая файл назначения + OFV, также сохраняет экспортированные образы в формате + сжатого VMDK, убедитесь, что на диске, содержащем эту + директорию достаточно свободного места для сохранения + образов. + </para><para> + Краткая форма этой опции <option>-o</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--legacy09</option></term> + <listitem><para> + Экспортирует в устаревший OVF-0.9 формат если продукт + виртуализации не полностью совместим со стандартном + OVF-1.0. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ovf09</option></term> + <listitem><para> + Экспортирует в формат OVF 0.9. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ovf10</option></term> + <listitem><para> + Экспортирует в формат OVF 1.0. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ovf20</option></term> + <listitem><para> + Экспортирует в формат OVF 2.0. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--manifest</option></term> + <listitem><para> + Создает манифест экспортированных файлов. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--options=<replaceable>аргумент</replaceable>,...</option></term> + <listitem><para> + Указывает информацию для управления точным содержимым + файла конфигурации. Укажите один или несколько разделенных + запятыми аргументами: + </para><variablelist> + <varlistentry> + <term><literal>manifest</literal></term> + <listitem><para> + Создает файл манифеста, который обнаруживает + поврежденные конфигурации при импорте. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>iso</literal></term> + <listitem><para> + Экспортирует образы DVD в файл ISO. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>nomacs</literal></term> + <listitem><para> + Исключает все MAC адреса. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>nomacsbutnat</literal></term> + <listitem><para> + Исключает все MAC адреса кроме тех, что в сети NAT. + </para></listitem> + </varlistentry> + </variablelist></listitem> + </varlistentry> + <varlistentry> + <term><option>--description=<replaceable>описание</replaceable></option></term> + <listitem><para> + Задает описание ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--eula=<replaceable>текст-лицензии</replaceable></option></term> + <listitem><para> + Задает текст лицензии конечного пользователя. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--eulafile=<replaceable>имя-файла</replaceable></option></term> + <listitem><para> + Задает файл лицензии конечного пользователя. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--product=<replaceable>имя-продукта</replaceable></option></term> + <listitem><para> + Задает имя продукта. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--producturl=<replaceable>URL-продукта</replaceable></option></term> + <listitem><para> + Задает URL продукта. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vendor=<replaceable>имя-поставщика</replaceable></option></term> + <listitem><para> + Задает имя поставщика. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vendorurl=<replaceable>URL-поставщика</replaceable></option></term> + <listitem><para> + Задает URl поставщика. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--version=<replaceable>информация-о-версии</replaceable></option></term> + <listitem><para> + Задает информацию о версии. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vmname=<replaceable>имя-ВМ</replaceable></option></term> + <listitem><para> + Задает имя экспортируемой ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vsys=<replaceable>номер-виртуальной-системы</replaceable></option></term> + <listitem><para> + Задает номер виртуальной системы. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-export-cloud"> + <title>Экспортировать виртуальную машину в &oci;</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage export</command> позволяет экспортировать + ВМ в провайдер облачной службы, например &oci;. По умолчанию + экспортированный образ диска преобразуется в формат сжатого VMDK. + Это минимизирует размер данных, передаваемых в облачную службу. + </para> + <para> + Некоторые из нижеследующих опций являются настройками конфигурации + экземпляра ВМ. Как результат, укажите Идентификатор Облака Oracle + (OCID) ресурса. Используйте консоль &oci; для просмотра OCID. + </para> + <variablelist> + <varlistentry> + <term><option>--output=<replaceable>провайдер-облачной-службы</replaceable></option></term> + <listitem><para> + Указывает краткое имя провайдера облачной службы, куда + необходимо экспортировать ВМ. Для &oci;, укажите + <literal>OCI://</literal>. + </para><para> + Краткая форма это опции <option>-o</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--opc10</option></term> + <listitem><para> + Экспорт в формат &oci;. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloud=<replaceable>номер-виртуальной-системы</replaceable></option></term> + <listitem><para> + Задает номер, идентифицирующий экспортируемую ВМ. + Нумерация начинается с <literal>0</literal> для первой ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vmname=<replaceable>имя-ВМ</replaceable></option></term> + <listitem><para> + Задает имя экспортируемой ВМ, используемое как имя + ВМ экземпляра в &oci;. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudprofile=<replaceable>имя-облачного-профиля</replaceable></option></term> + <listitem><para> + Задает облачный профиль, используемый для подключения к + провайдеру облачной службы. Облачный профиль содержит ваши + данные учетной записи &oci;, например ваш OCID пользователя + и отпечаток вашего публичного ключа. + </para><para> + Для использования облачных профилей у вас должны быть + необходимые разрешения в &oci;. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudshape=<replaceable>имя-облачной-формы</replaceable></option></term> + <listitem><para> + Задает форму, используемую экземпляром ВМ. Форма + определяет количество ЦПУ и размер памяти, выделенных + экземпляру ВМ. Убедитесь, что форма совместима с + экспортируемым образом. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--clouddomain=<replaceable>облачный-домен</replaceable></option></term> + <listitem><para> + Задает домен доступности, используемый экземпляром ВМ. + Введите полное имя домена доступности. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--clouddisksize=<replaceable>размер-диска-в-ГБ</replaceable></option></term> + <listitem><para> + Задает размер дискового пространства в гигабайтах, + используемый экспортированным образом диска. Допустимые + значения от 50 ГБ до 300 ГБ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudbucket=<replaceable>имя-корзины</replaceable></option></term> + <listitem><para> + Задает корзину где сохранять загруженные файлы. В &oci;, + корзина - это логический контейнер для хранения объектов. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudocivcn=<replaceable>OCI-VCN-ID</replaceable></option></term> + <listitem><para> + Задает OCID виртуальной облачной сети (VCN), используемой + экземпляром ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudocisubnet=<replaceable>ID-подсети-OCI</replaceable></option></term> + <listitem><para> + Задает OCID подсети VCN, используемой экземпляром ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudkeepobject=true | false</option></term> + <listitem><para> + Указывает сохранять ли экспортированный образ диска + в хранилище объектов Oracle. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudlaunchinstance=true | false</option></term> + <listitem><para> + Указывает запускать ли экземпляр ВМ после завершения + экспорта в &oci;. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudlaunchinstance=EMULATED | PARAVIRTUALIZED</option></term> + <listitem><para> + Указывает режим запуска экземпляра. + Паравиртуализированный режим дает более высокую + производительность. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudpublicip=true | false</option></term> + <listitem><para> + Указывает включать ли публичный IP адрес экземпляру ВМ. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Примет</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + Следующий пример показывает как экспортировать ВМ + <literal>myVM</literal> в &oci;. Аргументы опции команды + описывают конфигурацию ВМ <literal>myVM_Cloud</literal> + в &oci;. + </para> +<screen># VBoxManage export myVM --output=OCI:// --cloud=0 --vmname=myVM_Cloud \ +--cloudprofile="standard user" --cloudbucket=myBucket \ +--cloudshape=VM.Standard2.1 --clouddomain=US-ASHBURN-AD-1 --clouddisksize=50 \ +--cloudocivcn=ocid1.vcn.oc1.iad.aaaa... --cloudocisubnet=ocid1.subnet.oc1.iad.aaaa... \ +--cloudkeepobject=true --cloudlaunchinstance=true --cloudpublicip=true</screen> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-extpack.xml b/doc/manual/ru_RU/man_VBoxManage-extpack.xml new file mode 100644 index 00000000..31b8d8b6 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-extpack.xml @@ -0,0 +1,159 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage extpack +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-extpack" lang="en"> + + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage extpack</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-extpack</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-extpack</refname> + <refpurpose>управление пакетами расширения</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-extpack-install"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage extpack install</command> + <arg>--replace</arg> + <arg>--accept-license=<replaceable>sha256</replaceable></arg> + <arg choice="req"><replaceable>имя-tar-архива</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-extpack-uninstall"> + <command>VBoxManage extpack uninstall</command> + <arg>--force</arg> + <arg choice="req"><replaceable>имя</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-extpack-cleanup"> + <command>VBoxManage extpack cleanup</command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + + <refsect2 id="vboxmanage-extpack-install"> + <title>extpack install</title> + <remark role="help-copy-synopsis"/> + <para> + Устанавливает новый пакет расширения в систему. Эта команда завершится с ошибкой, + если более старая версия этого пакет уже установлена. Опция <option>--replace</option> + может быть использована для удаления пакетов более старой версии перед установкой + новой. + </para> + <variablelist> + <varlistentry> + <term><option>--replace</option></term><listitem><para>Удалить существующую версию пакета расширения.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--accept-license=<replaceable>sha256</replaceable></option></term> + <listitem> + <para>Принять текст лицензии с данным SHA-256 хеш значением.</para> + <para>VBoxManage отобразит SHA-256 значение при ручной установке. + Хэш, конечно может быть вычислен путем просмотра внутрь пакета + расширения и использования sha256sum или подобной на файле лицензии.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><replaceable>имя-tar-архива</replaceable></term> + <listitem> + <para>Файл, содержащий устанавливаемый пакет расширения.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-extpack-uninstall"> + <title>extpack uninstall</title> + <remark role="help-copy-synopsis"/> + <para> + Удаляет пакет расширения из системы. Подкоманда также завершится успешно, если + указанный пакет расширения отсутствует в системе. Можно использовать + <computeroutput>VBoxManage list extpacks</computeroutput> для просмотра имен + установленных пакетов расширений. + </para> + <variablelist> + <varlistentry> + <term><option>--force</option></term> + <listitem> + <para> Отменяет большинство отказов при удалении пакета расширений</para> + </listitem> + </varlistentry> + <varlistentry> + <term><replaceable>имя</replaceable></term> + <listitem> + <para>Имя удаляемого пакета расширения.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-extpack-cleanup"> + <title>extpack cleanup</title> + <remark role="help-copy-synopsis"/> + <para> + Используется для удаления временных файлов и директорий, оставшихся после + предыдущих операций установки или удаления пакетов расширений. + </para> + </refsect2> + + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="EXTPACK_UNINSTALL,EXTPACK"/> + <para> + Как посмотреть список пакетов расширений: +<screen>$ VBoxManage list extpacks +Пакеты расширений: 1 +Пакет no. 0: Oracle VM VirtualBox Extension Pack +Версия: 4.1.12 +Ревизия: 77218 +Редакция: +Описание: USB 2.0 Host Controller, VirtualBox RDP, PXE ROM with E1000 support. +VRDE модуль: VBoxVRDP +Годный: да +Почему не годен:</screen></para> + + <para>Как удалить пакет расширения: +<screen>$ VBoxManage extpack uninstall "Oracle VM VirtualBox Extension Pack" +0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100% +Успешно удалено "Oracle VM VirtualBox Extension Pack".</screen></para> + </refsect1> + +</refentry> + diff --git a/doc/manual/ru_RU/man_VBoxManage-getextradata.xml b/doc/manual/ru_RU/man_VBoxManage-getextradata.xml new file mode 100644 index 00000000..99136467 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-getextradata.xml @@ -0,0 +1,150 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage getextradata +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-getextradata" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-18 00:40:56 +0100 (Wed, 18 Jan 2023) $</pubdate> + <title>VBoxManage getextradata</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-getextradata</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-getextradata</refname> + <refpurpose>просмотр значений ключей, связанных с виртуальной машиной или конфигурацией</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-getextradata"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage getextradata</command> + <group choice="req"> + <arg choice="plain">global</arg> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <group choice="plain"> + <arg choice="req"><replaceable>ключ</replaceable></arg> + <arg>enumerate</arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage getextradata</command> позволяет получить + данные ключа, связанного с виртуальной машиной (ВМ) или с конфигурацией + &product-name;. + </para> + <variablelist> + <varlistentry> + <term><literal>global</literal></term> + <listitem><para> + Указывает, что надо получить информацию из конфигурации, + а не из ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>имя-ВМ</replaceable></term> + <listitem><para> + Указывает Универсальный Уникальный Идентификатор (UUID) или + имя ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>enumerate</literal></term> + <listitem><para> + Показывает все значения ключей для указанной ВМ + или конфигурации. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>ключ</replaceable></term> + <listitem><para> + Задает ключ, данные которого надо получить. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + Следующая команда получает значение ключа <literal>installdate</literal> + для ВМ <literal>Fedora5</literal>: + </para> +<screen>$ VBoxManage getextradata Fedora5 installdate +VirtualBox Command Line Management Interface Version <replaceable>номер-версии</replaceable> +Copyright (C) 2005-2023 Oracle and/or its affiliates + +Значение: 2006.01.01</screen> + <para> + Следующая команда получает информацию для всех ключей ВМ + <literal>OracleLinux7u4</literal>: + </para> +<screen>$ VBoxManage getextradata OracleLinux7u4 enumerate +Ключ: GUI/LastCloseAction, Значение: PowerOff +Ключ: GUI/LastGuestSizeHint, Значение: 1048,696 +Ключ: GUI/LastNormalWindowPosition, Значение: 851,286,1048,738</screen> + <para> + Следующая команда получает информацию для всех ключей в + конфигурации: + </para> +<screen>$ VBoxManage getextradata global enumerate +Ключ: GUI/Details/Elements, Значение: general,system,preview,display,storage,audio,network,usb,sharedFolders,description +Ключ: GUI/DetailsPageBoxes, Значение: general,system,preview,display,storage,audio,network,usb,sharedFolders,description +Ключ: GUI/GroupDefinitions/, Значение: m=43349dd8-2aa3-41b8-988f-0e255ce68090,m=9ebcd81e-5231-48ce-a27d-28218757f3fe,m=c690e8b1-93a0-4c95-9cd7-6437fff93251,m=f7c1e10d-3722-4891-887e-07b3c4104946 +Ключ: GUI/HideDescriptionForWizards, Значение: NewVM +Ключ: GUI/LastItemSelected, Значение: m=ol7u4 +Ключ: GUI/LastWindowPosition, Значение: 951,510,960,520 +Ключ: GUI/RecentFolderCD, Значение: C:/Users/user1 +Ключ: GUI/RecentListCD, Значение: C:\Users\user1\V1.iso,C:\Users\user1\V2.iso,C:\Users\user1\V3.iso +Ключ: GUI/SplitterSizes, Значение: 318,637 +Ключ: GUI/SuppressMessages, Значение: remindAboutMouseIntegration,remindAboutAutoCapture +Ключ: GUI/Toolbar/MachineTools/Order, Значение: Details +Ключ: GUI/Tools/LastItemsSelected, Значение: Welcome,Details +Ключ: GUI/UpdateCheckCount, Значение: 71 +Ключ: GUI/UpdateDate, Значение: 1 d, 2019-04-10, stable, 5.2.22 +Ключ: GUI/VirtualMediaManager/Details/Expanded, Значение: true</screen> + </refsect1> + + <refsect1> + <title>Смотрите также</title> + <para> + <xref linkend="vboxmanage-setextradata" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-guestcontrol.xml b/doc/manual/ru_RU/man_VBoxManage-guestcontrol.xml new file mode 100644 index 00000000..8201aec8 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-guestcontrol.xml @@ -0,0 +1,1288 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage guestcontrol +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-guestcontrol" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage guestcontrol</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-guestcontrol</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-guestcontrol</refname> + <refpurpose>управляет виртуальной машиной из хост-системы</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-run"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">run</arg> + <arg>--domain=<replaceable>имя-домена</replaceable></arg> + <arg>--dos2unix</arg> + <arg>--exe=<replaceable>имя-файла</replaceable></arg> + <arg>--ignore-orphaned-processes</arg> + <group> + <arg choice="plain">--no-wait-stderr</arg> + <arg choice="plain">--wait-stderr</arg> + </group> + <group> + <arg choice="plain">--no-wait-stdout</arg> + <arg choice="plain">--wait-stdout</arg> + </group> + <group> + <arg choice="plain">--passwordfile=<replaceable>файл-с-паролем</replaceable></arg> + <arg choice="plain">--password=<replaceable>пароль</replaceable></arg> + </group> + <arg>--profile</arg> + <arg>--putenv=<replaceable>имя-переменной</replaceable>=[<replaceable>значение</replaceable>]</arg> + <arg>--quiet</arg> + <arg>--timeout=<replaceable>миллисекунды</replaceable></arg> + <arg>--unix2dos</arg> + <arg>--unquoted-args</arg> + <arg>--username=<replaceable>имя-пользователя</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req">-- <replaceable>программа/аргумент0</replaceable> <arg rep="repeat"><replaceable>аргумент</replaceable></arg></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-start"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">start</arg> + <arg>--domain=<replaceable>имя-домена</replaceable></arg> + <arg>--exe=<replaceable>имя-файла</replaceable></arg> + <arg>--ignore-orphaned-processes</arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>файл-с-паролем</replaceable></arg> + <arg choice="plain">--password=<replaceable>пароль</replaceable></arg> + </group> + <arg>--profile</arg> + <arg>--putenv=<replaceable>имя-переменной</replaceable>=[<replaceable>значение</replaceable>]</arg> + <arg>--quiet</arg> + <arg>--timeout=<replaceable>миллисекунды</replaceable></arg> + <arg>--unquoted-args</arg> + <arg>--username=<replaceable>имя-пользователя</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req">-- <replaceable>программа/аргумент0</replaceable> <arg rep="repeat"><replaceable>аргумент</replaceable></arg></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-copyfrom"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">copyfrom</arg> + <arg>--domain=<replaceable>имя-домена</replaceable></arg> + <arg>--follow</arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>файл-с-паролем</replaceable></arg> + <arg choice="plain">--password=<replaceable>пароль</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--no-replace</arg> + <arg>--recursive</arg> + <arg>--target-directory=<replaceable>хост-директория-назначения</replaceable></arg> + <arg>--update</arg> + <arg>--username=<replaceable>имя-пользователя</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req"><replaceable>гостевой-источник0</replaceable></arg> + <arg choice="plain"><replaceable>гостевой-источник1</replaceable> [...]</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-copyto"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">copyto</arg> + <arg>--domain=<replaceable>имя-домена</replaceable></arg> + <arg>--follow</arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>файл-с-паролем</replaceable></arg> + <arg choice="plain">--password=<replaceable>пароль</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--no-replace</arg> + <arg>--recursive</arg> + <arg>--target-directory=<replaceable>гостевая-директория-назначения</replaceable></arg> + <arg>--update</arg> + <arg>--username=<replaceable>имя-пользователя</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req"><replaceable>хост-источник0</replaceable></arg> + <arg choice="plain"><replaceable>хост-источник1</replaceable> [...]</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-mkdir"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">mkdir</arg> + <arg>--domain=<replaceable>имя-домена</replaceable></arg> + <arg>--mode=<replaceable>режим</replaceable></arg> + <arg>--parents</arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>файл-с-паролем</replaceable></arg> + <arg choice="plain">--password=<replaceable>пароль</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--username=<replaceable>имя-пользователя</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req" rep="repeat"><replaceable>гостевая-директория</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-rmdir"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">rmdir</arg> + <arg>--domain=<replaceable>имя-домена</replaceable></arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>файл-с-паролем</replaceable></arg> + <arg choice="plain">--password=<replaceable>пароль</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--recursive</arg> + <arg>--username=<replaceable>имя-пользователя</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req" rep="repeat"><replaceable>гостевая-директория</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-rm"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">rm</arg> + <arg>--domain=<replaceable>имя-домена</replaceable></arg> + <arg>--force</arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>файл-с-паролем</replaceable></arg> + <arg choice="plain">--password=<replaceable>пароль</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--username=<replaceable>имя-пользователя</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req" rep="repeat"><replaceable>гостевая-директория</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-mv"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">mv</arg> + <arg>--domain=<replaceable>имя-домена</replaceable></arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>файл-с-паролем</replaceable></arg> + <arg choice="plain">--password=<replaceable>пароль</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--username=<replaceable>имя-пользователя</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req" rep="repeat"><replaceable>источник</replaceable></arg> + <arg choice="req"><replaceable>директория-назначения</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-mktemp"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">mktemp</arg> + <arg>--directory</arg> + <arg>--domain=<replaceable>имя-домена</replaceable></arg> + <arg>--mode=<replaceable>режим</replaceable></arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>файл-с-паролем</replaceable></arg> + <arg choice="plain">--password=<replaceable>пароль</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--secure</arg> + <arg>--tmpdir=<replaceable>имя-директории</replaceable></arg> + <arg>--username=<replaceable>имя-пользователя</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req"><replaceable>имя-шаблона</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-stat"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">stat</arg> + <arg>--domain=<replaceable>имя-домена</replaceable></arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>файл-с-паролем</replaceable></arg> + <arg choice="plain">--password=<replaceable>пароль</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--username=<replaceable>имя-пользователя</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req"><replaceable>имя-файла</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-list"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">list</arg> + <group choice="req"> + <arg choice="plain">all</arg> + <arg choice="plain">files</arg> + <arg choice="plain">processes</arg> + <arg choice="plain">sessions</arg> + </group> + <arg>--quiet</arg> + <arg>--verbose</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-closeprocess"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">closeprocess</arg> + <group> + <arg choice="plain">--session-id=<replaceable>ID</replaceable></arg> + <arg choice="plain">--session-name=<replaceable>имя-или-шаблон</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--verbose</arg> + <arg choice="req" rep="repeat"><replaceable>PID</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-closesession"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">closesession</arg> + <group> + <arg choice="plain">--all</arg> + <arg choice="plain">--session-id=<replaceable>ID</replaceable></arg> + <arg choice="plain">--session-name=<replaceable>имя-или-шаблон</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--verbose</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-updatega"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">updatega</arg> + <arg>--quiet</arg> + <arg>--verbose</arg> + <arg>--source=<replaceable>дополнения_гостевой_ос.ISO</replaceable></arg> + <arg>--wait-start</arg> + <arg>-- <arg rep="repeat"><replaceable>аргумент</replaceable></arg></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-watch"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="plain">watch</arg> + <arg>--quiet</arg> + <arg>--verbose</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage guestcontrol</command> позволяет + управлять гостевой виртуальной машиной (ВМ) из хост-системы. + Смотрите <xref linkend="guestadd-guestcontrol" />. + </para> + <refsect2> + <title>Общие опции и операнды</title> + <para> + Следующие опции могут быть использованы с любой подкомандой + <command>VBoxManage guestcontrol</command>: + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>имя-ВМ</replaceable></term> + <listitem><para> + Задает Универсальный Уникальный Идентификатор (UUID) или + имя ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--quiet</option></term> + <listitem><para> + Указывает, что команда производит более тихий вывод. + </para><para> + Краткая форма этой опции <option>-q</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--verbose</option></term> + <listitem><para> + Указывает, что команда производит более подробный вывод. + </para><para> + Краткая форма этой опции <option>-v</option>. + </para></listitem> + </varlistentry> + </variablelist> + <para> + Некоторые подкоманды <command>VBoxManage guestcontrol</command> + требуют, чтобы предоставили гостевые учетные данные для + идентификации. Эти подкоманды: + <command>copyfrom</command>, <command>copyto</command>, + <command>mkdir</command>, <command>mktemp</command>, + <command>mv</command>, <command>rmdir</command>, + <command>rm</command>, <command>run</command>, + <command>start</command> и <command>stat</command>. + </para> + <para> + Хотя вы не можете выполнять анонимные операции, пароль учетной + записи пользователя не является обязательным и зависит от + политики безопасности гостевой ОС. Если у пользователя + пароль не установлен, укажите пустой пароль. В ОС, таких как + Windows, возможно необходимо подстроить политику безопасности, + чтобы разрешить пользовательские учетные записи с пустым паролем. + В дополнение, могут применяться глобальные правила домена, и + поэтому они не могут быть изменены. + </para> + <para> + Следующие опции используются для аутентификации в гостевой ВМ: + </para> + <variablelist> + <varlistentry> + <term><option>--domain=<replaceable>имя-домена</replaceable></option></term> + <listitem><para> + Задает имя домена для гостевых Windows ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password=<replaceable>пароль</replaceable></option></term> + <listitem><para> + Задает пароль указанного пользователя. Если пароль не + указан в командной строке или файл с паролем пуст, + считается что у пользователя пустой пароль. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--passwordfile=<replaceable>имя-файла</replaceable></option></term> + <listitem><para> + Задает абсолютный путь к файлу в гостевой ОС, содержащему + пароль для указанного пользователя. Если файл с паролем + пуст или не указан пароль в командной строке, считается + что у пользователя пустой пароль. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--username=<replaceable>имя-пользователя</replaceable></option></term> + <listitem><para> + Задает существующего пользователя в гостевой ОС, от имени + которого запускается процесс. Если не указан, процесс + запускается от имени пользователя хоста. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2> + <title>Ограничения на гостевой процесс</title> + <para> + По умолчанию, можно запустить до пяти гостевых процессов + одновременно. Если запускается новый гостевой процесс, который + превысил этот лимит, старый не выполняющийся процесс удаляется + для запуска нового. Вы не сможете получить вывод из удаленного + гостевого процесса. Если все пять гостевых процессов активны и + выполняются, попытка запустить новый гостевой процесс будет + неудачна. + </para> + <para> + Можно модифицировать ограничения на выполнение гостевого процесса + двумя способами: + </para> + <itemizedlist> + <listitem><para> + Используя команду <command>VBoxManage setproperty</command> + для обновления значения гостевого свойства + <literal>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</literal>. + </para></listitem> + <listitem><para> + Используя команду <command>VBoxService</command> и указывая + опцию <option>--control-procs-max-kept=<replaceable>value</replaceable></option>. + </para></listitem> + </itemizedlist> + <para> + Необходимо перезагрузить гостевую ОС после изменения ограничения. + </para> + <para> + Можно обслуживать неограниченное количество гостевых процессов + путем указания значения <literal>0</literal>, однако, это не + рекомендуется. + </para> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-run"> + <title>Запуск команды в гостевой виртуальной машине</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage guestcontrol + <replaceable>имя-ВМ</replaceable> run</command> позволяет + исполнять программу в гостевой ВМ. Стандартные потоки ввода, + вывода и ошибок перенаправляются из ВМ в хост-систему до + завершения программы. + </para> + <note> + <para> + ОС Windows навязывает определенные ограничения на графические + приложения. Смотрите <xref linkend="KnownIssues" />. + </para> + </note> + <variablelist> + <varlistentry> + <term><option>--exe=<replaceable>путь-до-исполняемого-файла</replaceable></option></term> + <listitem><para> + Указывает абсолютный путь к исполняемому файлу для запуска + в гостевой ВМ. Например <filename>C:\Windows\System32\calc.exe</filename>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--timeout=<replaceable>миллисекунды</replaceable></option></term> + <listitem><para> + Указывает максимальное время в миллисекундах, + выделенное для работы программы. Во время работы + программы <command>VBoxManage</command> получает ее + вывод. + </para><para> + Если не указывается величина ожидания, <command>VBoxManage</command> + ждет до бесконечности окончания программы или возникновения ошибки. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--putenv=<replaceable>имя</replaceable>=[<replaceable>значение</replaceable>]</option></term> + <listitem><para> + Устанавливает, изменяет или удаляет переменные окружения + в окружении гостевой ВМ. + </para><para> + Когда создается гостевой процесс, он работает в + стандартной среде гостевой ОС задаваемой по умолчанию. + Используйте эту опцию, чтобы изменить переменные окружения + в среде по умолчанию. + </para><para> + Используйте опцию + <option>--putenv=<replaceable>имя</replaceable>=[<replaceable>значение</replaceable>]</option> + для установки или изменения переменной окружения указываемой через <replaceable>имя</replaceable>. + </para><para> + Используйте опцию + <option>--putenv=<replaceable>имя</replaceable>=[<replaceable>значения</replaceable>]</option> + для удаления переменной окружения указанной через <replaceable>имя</replaceable>. + </para><para> + Убедитесь, что переменная или значение, содержащие + пробелы должны быть заключены в кавычки. + </para><para> + Необходимо указать опцию <option>--putenv</option> + для каждой модифицируемой переменной окружения. + </para><para> + Краткая форма этой опции <option>-E</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unquoted-args</option></term> + <listitem><para> + Отключает экранированные двойные кавычки аргументов, + передаваемые программе. Например <literal>\"fred\"</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ignore-orphaned-processes</option></term> + <listitem><para> + Игнорирует процессы-сироты. Еще не реализовано. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--profile</option></term> + <listitem><para> + Использует профиль оболочки, чтобы указать используемое + окружение. Еще не реализовано. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--no-wait-stdout</option></term> + <listitem><para> + Не ждет завершения гостевого процесса или получения его + кода завершения и каких-либо объяснений сбоя. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--wait-stdout</option></term> + <listitem><para> + Ждет завершения процесса, чтобы получить его код + завершения и любые объяснения сбоя. Команда + <command>VBoxManage</command> принимает данные со + стандартного потока вывода гостевого процесса во + время выполнения процесса. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--no-wait-stderr</option></term> + <listitem><para> + Не ждет завершения гостевого процесса, чтобы + получить его код завершения, сообщения об + ошибках и флаги. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--wait-stderr</option></term> + <listitem><para> + Ждет завершения гостевого процесса для получения + его кода завершения, сообщений об ошибках и флаги. + Команда <command>VBoxManage</command> принимает данные + со стандартного потока ошибок гостевого процесса во + время выполнения процесса. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dos2unix</option></term> + <listitem><para> + Преобразует гостевой DOS или Windows вывод в UNIX или + Linux вывод. Это преобразование изменяет завершения строк + с CR + LF на LF. Еще не реализовано. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unix2dos</option></term> + <listitem><para> + Преобразует гостевой UNIX или Linux вывод в DOS или + Windows вывод. Это преобразование изменяет завершения строк + с LF на CR + LF. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>-- <replaceable>программа/аргумент0</replaceable> [<replaceable>аргумент</replaceable>...]</option></term> + <listitem><para> + Задает имя программы и любые аргументы, передаваемые + программе. + </para><para> + Убедитесь, что все аргументы команды, содержащие пробелы, + заключены в кавычки. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-start"> + <title>Запуск команды в гостевой виртуальной машине</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage guestcontrol + <replaceable>имя-ВМ</replaceable> start</command> позволяет + выполнить гостевую программу до ее завершения. + </para> + <note> + <para> + ОС Windows навязывает определенные ограничения на графические + приложения. Смотрите <xref linkend="KnownIssues" />. + </para> + </note> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-copyfrom"> + <title>Копирование файла из гостевой виртуальной машины в директорию в хост-системы</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage guestcontrol + <replaceable>имя-ВМ</replaceable> copyfrom</command> позволяет + скопировать файл из гостевой ВМ в хост-систему. + </para> + <variablelist> + <varlistentry> + <term><option>--dereference</option></term> + <listitem><para> + Включает следование по символическим ссылкам в гостевой + файловой системе. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--no-replace</option></term> + <listitem><para> + Only copies a file if it does not exist on the host yet. + </para><para> + The short form of this option is <option>-n</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recursive</option></term> + <listitem><para> + Рекурсивно копирует файлы и директории из указанной + директории в гостевой ВМ. + </para><para> + Краткая форма этой опции <option>-R</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--target-directory=<replaceable>хост-директория-назначения</replaceable></option></term> + <listitem><para> + Задает абсолютный путь к директории назначения в + хост-системе. Например <filename>C:\Temp</filename>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--update</option></term> + <listitem><para> + Only copies a file if the guest file is newer than on the host. + </para><para> + The short form of this option is <option>-u</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal><replaceable>гостевой-источник0</replaceable> [<replaceable>гостевой-источник1</replaceable> [...]]</literal></term> + <listitem><para> + Задает абсолютный путь одного или нескольких файлов + для копирования из гостевой ВМ. Например + <filename>C:\Windows\System32\calc.exe</filename>. Можно + использовать подстановочные знаки. Например + <filename>C:\Windows\System*\*.dll</filename>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-copyto"> + <title>Копирует файл в директорию на гостевой виртуальной машине из хост-системы</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage guestcontrol + <replaceable>имя-ВМ</replaceable> copyto</command> позволяет + скопировать файл из хост-системы в гостевую ВМ. + </para> + <variablelist> + <varlistentry> + <term><option>--dereference</option></term> + <listitem><para> + Включает следование по символическим ссылкам в хост-системе. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--no-replace</option></term> + <listitem><para> + Only copies a file if it does not exist on the guest yet. + </para><para> + The short form of this option is <option>-n</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recursive</option></term> + <listitem><para> + Рекурсивно копирует файлы и директории из указанной + директории в хост-системе. + </para><para> + Краткая форма этой опции <option>-R</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--target-directory=<replaceable>гостевая-директория-назначения</replaceable></option></term> + <listitem><para> + Задает абсолютный путь директории назначения в гостевой + ВМ. Например <filename>C:\Temp</filename>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--update</option></term> + <listitem><para> + Only copies a file if the host file is newer than on the guest. + </para><para> + The short form of this option is <option>-u</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal><replaceable>хост-источник0</replaceable> [<replaceable>хост-источник1</replaceable> [...]]</literal></term> + <listitem><para> + Задает абсолютный путь одного или нескольких файлов для + копирования из хост-системы. Например + <filename>C:\Windows\System32\calc.exe</filename>. Можно + использовать подстановочные знаки для указания нескольких + файлов. Например <filename>C:\Windows\System*\*.dll</filename>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-mkdir"> + <title>Создает директорию в гостевой виртуальной машине</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage guestcontrol + <replaceable>имя-ВМ</replaceable> mkdir</command> позволяет + создать один или несколько директорий в гостевой ВМ. + </para> + <para> + Альтернативные формы этой подкоманды: <command>md</command>, + <command>createdir</command> и <command>createdirectory</command>. + </para> + <variablelist> + <varlistentry> + <term><option>--parents</option></term> + <listitem><para> + Создает все отсутствующие родительские директории по + отношению к указанной. + </para><para> + Например, если попытаться создать директорию + <filename>D:\Foo\Bar</filename> и директория + <filename>D:\Foo</filename> не существует, использование + <option>--parents</option> создаст отсутствующую + директорию <filename>D:\Foo</filename>. Однако, если + попытаться создать <filename>D:\Foo\Bar</filename> и + не указать опцию <option>--parents</option>, команда + завершится неудачей. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mode=<replaceable>режим</replaceable></option></term> + <listitem><para> + Задает режим разрешений для указанной директории. + Если также используется опция <option>--parents</option>, + этот режим задается также для всех ее родительских + директорий. <replaceable>режим</replaceable> - это + четыре восьмеричные цифры, например <literal>0755</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal><replaceable>гостевая-директория</replaceable> [<replaceable>гостевая-директория</replaceable>...]</literal></term> + <listitem><para> + Задает абсолютный путь к одной или нескольким директориям + для создания в гостевой ВМ. Например <filename>D:\Foo\Bar</filename>. + </para><para> + Если все относящиеся к указанной родительские директории + не существуют в гостевой ВМ, необходимо использовать + опцию <option>--parents</option>. + </para><para> + У вас должно быть достаточно прав в гостевой ВМ, чтобы + создать указанную и ее родительские директории. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-rmdir"> + <title>Удалить директорию из гостевой виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage guestcontrol + <replaceable>имя-ВМ</replaceable> rmdir</command> позволяет + удалить указанную директорию из гостевой ВМ. + </para> + <para> + Альтернативные формы этой подкоманды <command>removedir</command> + и <command>removedirectory</command>. + </para> + <variablelist> + <varlistentry> + <term><option>--recursive</option></term> + <listitem><para> + Рекурсивно удаляет директории из указанной в гостевой ВМ. + </para><para> + Краткая форма этой опции <option>-R</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal><replaceable>гостевая-директория</replaceable> [<replaceable>гостевая-директория</replaceable>...]</literal></term> + <listitem><para> + Задает абсолютный путь к одной или нескольким директориям + для удаления в гостевой ВМ. Можно использовать + подстановочные знаки в именах директорий. Например + <filename>D:\Foo\*Bar</filename>. + </para><para> + У вас должно быть достаточно прав в гостевой ВМ, чтобы + удалить указанную и ее родительские директории. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-rm"> + <title>Удалить файл из гостевой виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage guestcontrol + <replaceable>имя-ВМ</replaceable> rm</command> позволяет + удалить указанный файл из гостевой ВМ. + </para> + <para> + Альтернативная форма этой подкоманды <command>removefile</command>. + </para> + <variablelist> + <varlistentry> + <term><option>--force</option></term> + <listitem><para> + Принудительно выполняет операцию и отменяет любые + запросы подтверждения. + </para><para> + Краткая форма этой опции <option>-f</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal><replaceable>гостевой-файл</replaceable> [<replaceable>гостевой-файл</replaceable>...]</literal></term> + <listitem><para> + Задает абсолютный путь одного или нескольких файлов для + удаления из гостевой ВМ. Можно использовать + подстановочные знаки в именах файлов. Например + <filename>D:\Foo\Bar\text*.txt</filename>. + </para><para> + У вас должно быть достаточно прав в гостевой ВМ, чтобы + удалить указанный файл. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-mv"> + <title>Переименовать файл или директорию в гостевой виртуальной машине</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage guestcontrol + <replaceable>имя-ВМ</replaceable> mv</command> позволяет + переименовать файлы и директории в гостевой ВМ. + </para> + <para> + Альтернативная форма этой подкоманды <command>move</command>, + <command>ren</command> и <command>rename</command>. + </para> + <variablelist> + <varlistentry> + <term><literal><replaceable>гостевой-источник</replaceable> [<replaceable>гостевой-источник</replaceable>...]</literal></term> + <listitem><para> + Задает абсолютный путь к файлу или единичной директории + для перемещения или переименования в гостевой ВМ. Можно + использовать подстановочные знаки в именах файлов. + </para><para> + У вас должно быть достаточно прав в гостевой ВМ для + доступа к указанному файлу или директории. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>назначение</replaceable></term> + <listitem><para> + Задает абсолютный путь к переименовываемым файлу или + директории, или директории назначения, куда + перемещать файлы. Если перемещается только один + файл, <replaceable>назначение</replaceable> может + быть как файлом так и директорией, иначе + <replaceable>назначение</replaceable> должно быть + директорией. + </para><para> + У вас должно быть достаточно прав в гостевой ВМ для + доступа к файлу или директории назначения. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-mktemp"> + <title>Создать временный файл или директорию в гостевой виртуальной машине</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage guestcontrol + <replaceable>имя-ВМ</replaceable> mktemp</command> позволяет + создать временный файл или директорию в гостевой ВМ. Можно + использовать эту команду для помощи с последующим копированием + файлов из хост-системы в гостевую ВМ. По умолчанию, эта команда + создает файл или директорию в платформо-зависимой директории + <filename>temp</filename> гостевой ВМ. + </para> + <para> + Альтернативные формы этой подкоманды <command>createtemp</command> + и <command>createtemporary</command>. + </para> + <variablelist> + <varlistentry> + <term><option>--directory</option></term> + <listitem><para> + Создает временную директорию указанную в операнде + <replaceable>шаблон</replaceable>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--secure</option></term> + <listitem><para> + Обеспечивает безопасное создание файлов и каталогов, + устанавливая режим разрешений <literal>0755</literal>. + Любая операция, которая не может быть произведена + безопасно приведет к неудаче. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mode=<replaceable>режим</replaceable></option></term> + <listitem><para> + Задает режим разрешений, используемый указанной директорией. + <replaceable>режим</replaceable> - это четыре восьмеричные + цифры, например <literal>0755</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tmpdir=<replaceable>директория</replaceable></option></term> + <listitem><para> + Задает абсолютный путь к директории в гостевой ВМ, где + создавать указанный файл или директорию. Если не указан, + <replaceable>директория</replaceable> - это + платформо-зависимая директория <filename>temp</filename>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>шаблон</replaceable></term> + <listitem><para> + Задает шаблон имени для временного файла без пути к + директории. Шаблон имени файла должен содержать как + минимум одну последовательности трех последовательных + символов X или должен заканчиваться ими. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-stat"> + <title>Показать статус файла или файловой системы в гостевой виртуальной машине.</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage guestcontrol + <replaceable>имя-ВМ</replaceable> stat</command> позволяет + отобразить статус файлов или или файловых систем в гостевой + ВМ. + </para> + <variablelist> + <varlistentry> + <term><literal><replaceable>файл</replaceable> [<replaceable>файл</replaceable> ...]</literal></term> + <listitem><para> + Задает абсолютный путь к файлу или файловой системе в + гостевой ВМ. Например <filename>/home/foo/a.out</filename>. + </para><para> + У вас должно быть достаточно прав в гостевой ВМ для + доступа к указанным файлам или файловым системам. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-list"> + <title>Показать настройки и информацию о статусе гостевой виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage guestcontrol + <replaceable>имя-ВМ</replaceable> list</command> позволяет + показать настройки гостевого управления и информацию о статусе. + Например, вывол показывает открытые гостевые сессии, гостевые + процессы и файлы. + </para> + <variablelist> + <varlistentry> + <term><literal>all</literal>|<literal>sessions</literal>|<literal>processes</literal>|<literal>files</literal></term> + <listitem><para> + Указывает тип отображаемой информации. + <literal>all</literal> показывает все доступные данные, + <literal>sessions</literal> показывает гостевые сессии, + <literal>processes</literal> показывает процессы и + <literal>files</literal> показывает файлы. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-closeprocess"> + <title>Завершить процесс в сессии гостевой виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage guestcontrol + <replaceable>имя-ВМ</replaceable> closeprocess</command> позволяет + завершить гостевой процесс работающий в гостевой сессии. + Указывайте процесс через идентификатор процесса (PID) и сессию, + используя ID сессии или имя. + </para> + <variablelist> + <varlistentry> + <term><option>--session-id=<replaceable>ID</replaceable></option></term> + <listitem><para> + Задает ID гостевой сессии. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--session-name=<replaceable>имя</replaceable>|<replaceable>шаблон</replaceable></option></term> + <listitem><para> + Задает имя гостевой сессии. Используйте шаблон, + содержащий подстановочные знаки для указания + нескольких сессий. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal><replaceable>PID</replaceable> [<replaceable>PID</replaceable> ...]</literal></term> + <listitem><para> + Задает список PID гостевых процессов для завершения. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-closesession"> + <title>Закрыть сессию гостевой виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage guestcontrol + <replaceable>имя-ВМ</replaceable> closesession</command> позволяет + закрыть гостевую сессию. Указывайте гостевую сессию или через ID + сессии или через имя. + </para> + <variablelist> + <varlistentry> + <term><option>--session-id=<replaceable>ID</replaceable></option></term> + <listitem><para> + Задает ID гостевой сессии. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--session-name=<replaceable>имя</replaceable>|<replaceable>шаблон</replaceable></option></term> + <listitem><para> + Задает имя гостевой сессии. Используйте шаблон, + содержащий подстановочные знаки для указания + нескольких сессий. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--all</option></term> + <listitem><para> + Закрывает все гостевые сессии. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-updatega"> + <title>Обновить ПО Дополнений Гостевой ОС в гостевой виртуальной машине</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage guestcontrol + <replaceable>имя-ВМ</replaceable> updatega</command> позволяет + обновить ПО Дополнений Гостевой ОС, установленное в указанной + гостевой ВМ. + </para> + <para> + Альтернативные формы этой подкоманды + <command>updateadditions</command> и + <command>updateguestadditions</command>. + </para> + <variablelist> + <varlistentry> + <term><option>--source=<replaceable>новый-путь-к-iso</replaceable></option></term> + <listitem><para> + Задает абсолютный путь к <filename>.ISO</filename> файлу + Дополнений Гостевой ОС в гостевой ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--reboot</option></term> + <listitem><para> + Автоматический перезагружает гостевую систему после успешного + обновления Дополнений Гостевой ОС. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--timeout=<replaceable>миллисекунды</replaceable></option></term> + <listitem><para> + Задает максимальное время ожидания (в миллисекундах) заверешения + полного обновления Дополнений Гостевой ОС. По умолчанию, максимальное + время ожидания не используется. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--verify</option></term> + <listitem><para> + Проверяет, что Дополнения Гостевой ОС обновлены успешно после + успешной установки. Перезагрузка гостя обязательна. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--wait-ready</option></term> + <listitem><para> + Ждет когда текущие Дополения Гостевой ОС готовы для + обновления Дополений Гостевой ОС. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--wait-start</option></term> + <listitem><para> + Запускает <command>VBoxManage</command> процесс обновления + в гостевой ВМ и ждет начала обновления Дополений Гостевой ОС + перед завершения процесса <command>VBoxManage</command>. + </para><para> + По умолчанию, команда <command>VBoxManage</command> ждет + завершения обновления Дополений Гостевой ОС перед + завершением. Используйте эту опцию когда работающий + процесс <command>VBoxManage</command> влияет на + взаимодействие между установщиком и гостевой ОС. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>-- <replaceable>аргумент</replaceable> [<replaceable>аргумент</replaceable> ...]</option></term> + <listitem><para> + Задает необязательные аргументы командной строки, которые + передаются программе обновления Дополнений Гостевой ОС. + Можно использовать опцию <option>--</option> для передачи + соответствующих аргументов программе обновления для + модернизации еще не установленных функций. + </para><para> + Убедитесь, что командные аргументы, содержащие пробелы, + заключены в кавычки. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-waitrunlevel"> + <title>Ждать гостевой уровень выполнения</title> + <para> + Команда <command>VBoxManage guestcontrol + <replaceable>имя-ВМ</replaceable> waitrunlevel</command> позволяет + ожидать достижения гостевого уровня выполнения. + </para> + <variablelist> + <varlistentry> + <term><option>--timeout=<replaceable>миллисекунды</replaceable></option></term> + <listitem><para> + Задать максимальное время ожидания (в миллисекундах) + достижения уровня выполнения. По умолчанию максимальное + время ожидания не используется. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option><replaceable>system</replaceable>|<replaceable>userland</replaceable>|<replaceable>desktop</replaceable></option></term> + <listitem><para> + Задает ожидаемый уровень выполнения + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-watch"> + <title>Показать текущую активность гостевого управления.</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage guestcontrol + <replaceable>имя-ВМ</replaceable> watch</command> позволяет + показать текущую активность гостевого управления. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + Следующая команда <command>VBoxManage guestcontrol run</command> + выполняет команду <command>ls -l /usr</command> в Oracle Linux ВМ + <literal>My OL VM</literal> от имени пользователя + <literal>user1</literal>. + </para> +<screen> +$ VBoxManage --nologo guestcontrol "My OL VM" run --exe "/bin/ls" \ +--username user1 --passwordfile pw.txt --wait-stdout -- -l /usr +</screen> + <para> + Опция <option>--exe</option> указывает абсолютный путь команды + для запуска в гостевой ВМ, <filename>/bin/ls</filename>. + Используйте опцию <option>--</option> для передачи любых + аргументов, следующих после команды <command>ls</command>. + </para> + <para> + Используйте опцию <option>--username</option> для указания + имени пользователя, <literal>user1</literal> и опцию + <option>--passwordfile</option> для указания имения файлы, + содержащего пароль для пользователя <literal>user1</literal>, + <filename>pw.txt</filename>. + </para> + <para> + Опция <option>--wait-stdout</option> ожидает завершения + гостевого процесса <command>ls</command> перед передачей + кода заверешения и вывода команды. Опция <option>--nologo</option> + подавляет вывод информации о логотипе. + </para> + <para> + Следующая команда <command>VBoxManage guestcontrol run</command> + выполняет команду <command>ipconfig</command> в Windows ВМ + <literal>My Win VM</literal> от имени пользователя + <literal>user1</literal>. Стандартные потоки ввода, вывода + и ошибок перенаправляются из ВМ в хост-систему до завершения + программы. + </para> +<screen> +$ VBoxManage --nologo guestcontrol "My Win VM" run \ +--exe "c:\\windows\\system32\\ipconfig.exe" \ +--username user1 --passwordfile pw.txt --wait-stdout +</screen> + <para> + Опция <option>--exe</option> задает абсолютный путь команды для + запуска в гостевой ВМ, + <filename>c:\windows\system32\ipconfig.exe</filename>. Двойные + слеши показанные в этом примере требуются только в UNIX + хост-системах. + </para> + <para> + Используйте опцию <option>--username</option> для указания имени + пользователя, <literal>user1</literal> и опцию + <option>--passwordfile</option> для указания имени файла, + содержащего пароль для пользователя <literal>user1</literal>, + <filename>pw.txt</filename>. + </para> + <para> + Опция <option>--wait-stdout</option> ожидает завершения + гостевого процесса <command>ls</command> перед передачей + кода заверешения и вывода команды. Опция <option>--nologo</option> + подавляет вывод информации о логотипе. + </para> + <para> + Следующая команда <command>VBoxManage guestcontrol start</command> + выполняет команду <command>ls -l /usr</command> в Oracle Linux ВМ + <literal>My OL VM</literal> до завершения программы. + </para> +<screen> +$ VBoxManage --nologo guestcontrol "My Win VM" start \ +--exe "c:\\windows\\system32\\ipconfig.exe" \ +--username user1 --passwordfile pw.txt --wait-stdout +</screen> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-guestproperty.xml b/doc/manual/ru_RU/man_VBoxManage-guestproperty.xml new file mode 100644 index 00000000..772def2d --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-guestproperty.xml @@ -0,0 +1,334 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage guestproperty +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-guestproperty" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage guestproperty</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-guestproperty</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-guestproperty</refname> + <refpurpose>управляет гостевыми свойствами виртуальной машины</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <cmdsynopsis id="synopsis-vboxmanage-guestproperty-get"> + <command>VBoxManage guestproperty get</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="req"><replaceable>имя-свойства</replaceable></arg> + <arg>--verbose</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestproperty-enumerate"> + <command>VBoxManage guestproperty enumerate</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg>--patterns=<replaceable>шаблоны</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestproperty-set"> + <command>VBoxManage guestproperty set</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="req"><replaceable>имя-свойства</replaceable></arg> + <arg><replaceable>значение-свойства</replaceable><arg>--flags=<replaceable>флаги</replaceable></arg></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestproperty-unset"> + <command>VBoxManage guestproperty unset</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="req"><replaceable>имя-свойства</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestproperty-wait"> + <command>VBoxManage guestproperty wait</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="req"><replaceable>шаблоны</replaceable></arg> + <arg>--timeout=<replaceable>миллисекунды</replaceable></arg> + <arg>--fail-on-timeout</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage guestproperty</command> позволяет + установить или получить свойства работающей виртуальной машины (ВМ). + Смотрите <xref linkend="guestadd-guestprops" />. Гостевые свойства - + это произвольные пары строк в виде имя-значение, которые могут + быть записаны и прочтены как с гостевой системы так и с хоста. + В результате эти свойства могут быть использованы как канал + связи небольшого объема для строк при условии, что гость работает + и установлены Дополнения Гостевой ОС. Также, Дополнения + Гостевой ОС автоматически устанавливают и поддерживают значения + ключей, начинающихся с <literal>/VirtualBox/</literal>. + </para> + <refsect2> + <title>Общие командные операнды</title> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>имя-ВМ</replaceable></term> + <listitem><para> + Задает Универсальный Уникальный Идентификатор (UUID) или + имя ВМ. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestproperty-enumerate"> + <title>Показать все свойства виртуальной машины</title> + <para> + Команда <command>VBoxManage guestproperty enumerate</command> + показывает каждое гостевое свойство и его значение для + указанной ВМ. Заметим, что вывод ограничен если невозможно + подсоединиться к процессу гостевой службы, например потому + что ВМ не работает или не установлены Дополнения Гостевой ОС. + </para> + <variablelist> + <varlistentry> + <term><option>--patterns=<replaceable>шаблон</replaceable></option></term> + <listitem><para> + Фильтрует список свойств основанный на указанном + шаблоне, который может содержать следующие + подстановочные знаки: + </para><variablelist> + <varlistentry> + <term><literal>*</literal> (звездочка)</term> + <listitem><para> + Представляет любое количество произвольных символов. + Например, шаблон <literal>/VirtualBox*</literal> + соответствует всем свойствам, начинающимся с + <literal>/VirtualBox</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>?</literal> (знак вопроса)</term> + <listitem><para> + Представляет один произвольный символ. Например + шаблон <literal>fo?</literal> соответствует и + <literal>foo</literal> и <literal>for</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>|</literal> (канал)</term> + <listitem><para> + Задает несколько альтернативных шаблонов. + Например шаблон <literal>s*|t*</literal> + соответствует свойствам, начинающимся с + <literal>s</literal> или <literal>t</literal>. + </para></listitem> + </varlistentry> + </variablelist></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestproperty-get"> + <title>Получить значение свойства виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage guestproperty get</command> + получает значение указанного свойства. Если свойство не + найдено, например, потому что гостевая система сейчас не + работает, команда выдает следующее сообщение: + </para> +<screen>No value set!</screen> + <variablelist> + <varlistentry> + <term><replaceable>имя-свойства</replaceable></term> + <listitem><para> + Задает имя свойства. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--verbose</option></term> + <listitem><para> + Выдает значение свойства, метку времени и любые указанные + аттрибуты значения. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestproperty-set"> + <title>Задать значение свойства для виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage guestproperty set</command> позволяет + задать свойство гостевой системы, указывая свойство и его значение. + Если значение опущено, свойство удаляется. + </para> + <variablelist> + <varlistentry> + <term><replaceable>имя-свойства</replaceable></term> + <listitem><para> + Задает имя свойства. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>значение-свойства</replaceable></term> + <listitem><para> + Указывает значение свойства. Если значение не указано, + существующее значение удаляется. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--flags=<replaceable>флаги</replaceable></option></term> + <listitem><para> + Задает дополнительные аттрибуты значения. Могут быть указаны + следующие аттрибуты в виде списка значений разделенных запятыми: + </para><variablelist> + <varlistentry> + <term><literal>TRANSIENT</literal></term> + <listitem><para> + Удаляет значение с данными ВМ при завершении ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>TRANSRESET</literal></term> + <listitem><para> + Удаляет значение при завершении или рестарте ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>RDONLYGUEST</literal></term> + <listitem><para> + Задает значение, которое может быть изменено только + хостом. Гостевая система может только прочитать + значение свойства. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>RDONLYHOST</literal></term> + <listitem><para> + Задает значение, которое может быть изменено только + гостевой системой. Хост может только прочитать + значение свойства. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>READONLY</literal></term> + <listitem><para> + Задает неизменяемое значение. + </para></listitem> + </varlistentry> + </variablelist></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestproperty-wait"> + <title>Ожидать создания, удаления или изменения значения свойства</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage guestproperty wait</command> ожидает + создания, удаления или изменения определенного свойства, + описанного строкой шаблона. + </para> + <variablelist> + <varlistentry> + <term><replaceable>шаблоны</replaceable></term> + <listitem><para> + Задает шаблон, соответствующий свойствам, необходимым + для ожидания. По информации о подстановочных знаках + в шаблоне смотрите описание опции + <option>--patterns</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--timeout<replaceable>миллисекунды</replaceable></option></term> + <listitem><para> + Задает количество миллисекунд ожидания. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--fail-on-timeout</option></term> + <listitem><para> + Указывает, что команда должна закончиться неудачей + если достигнут порог ожидания. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestproperty-unset"> + <title>Удалить значение свойства виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage guestproperty unset</command> + удаляет значение гостевого свойства. + </para> + <para> + Альтернативная формат этой подкоманды <command>delete</command>. + </para> + <variablelist> + <varlistentry> + <term><replaceable>имя-свойства</replaceable></term> + <listitem><para> + Задает имя свойства. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда выдает список гостевых свойств и их значений + для ВМ <literal>win8</literal>. + </para> +<screen>$ VBoxManage guestproperty enumerate win8</screen> + <para> + Следующая команда создает гостевое свойство называемое + <literal>region</literal> для ВМ <literal>win8</literal>. + Значение свойства устанавливается в <literal>west</literal>. + </para> +<screen>$ VBoxManage guestproperty set win8 region west</screen> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-hostonlyif.xml b/doc/manual/ru_RU/man_VBoxManage-hostonlyif.xml new file mode 100644 index 00000000..8ad67bd1 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-hostonlyif.xml @@ -0,0 +1,199 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage hostonlyif +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-hostonlyif" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage hostonlyif</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-hostonlyif</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-hostonlyif</refname> + <refpurpose>управление сетевыми интерфейсами хоста</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <cmdsynopsis id="synopsis-vboxmanage-hostonlyif-ipconfig"> + <command>VBoxManage hostonlyif ipconfig</command> + <arg choice="req"><replaceable>имя-интерфейса</replaceable></arg> + <group> + <arg choice="plain">--dhcp</arg> + <arg choice="plain">--ip=<replaceable>IPv4-адрес</replaceable> <arg>--netmask=<replaceable>IPv4-маска</replaceable></arg></arg> + <arg choice="plain">--ipv6=<replaceable>IPv6-адрес</replaceable> <arg>--netmasklengthv6=<replaceable>длина</replaceable></arg></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-hostonlyif-create"> + <command>VBoxManage hostonlyif create</command> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-hostonlyif-remove"> + <command>VBoxManage hostonlyif remove</command> + <arg choice="req"><replaceable>имя-интерфейса</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage hostonlyif</command> позволяет + изменить IP конфигурацию интерфейса сети хоста. + Описание сетей хоста смотрите <xref linkend="network_hostonly" />. + Каждый интерфейс сети хоста идентифицируется через имя и + может использовать внутренний DHCP сервер или ручную настройку + IP, как IPv4 так и IPv6. + </para> + <refsect2 id="vboxmanage-hostonlyif-ipconfig"> + <title>Настроить интерфейс сети хоста</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage hostonlyif ipconfig</command> + настраивает интерфейс сети хоста. + </para> + <variablelist> + <varlistentry> + <term><replaceable>имя-интерфейса</replaceable></term> + <listitem><para> + Задает имя сетевого интерфейса. Имя в форме + <literal>vboxnet</literal><replaceable>N</replaceable>, + где <replaceable>N</replaceable> - это экземпляр + интерфейса. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dhcp</option></term> + <listitem><para> + Использует DHCP для сетевого интерфейса. + </para><para> + Эта опция не может использоваться с опциями + <option>--ip</option>, <option>--ipv6</option>, + <option>--netmask</option> и + <option>--netmasklengthv6</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ip=<replaceable>IPv4-адрес</replaceable></option></term> + <listitem><para> + Задает IPv4 адрес сетевого интерфейса. + </para><para> + Эта опция не может использоваться с опциями + <option>--dhcp</option>, <option>--ipv6</option> + и <option>--netmasklengthv6</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--netmask=<replaceable>IPv4-маска</replaceable></option></term> + <listitem><para> + Задает IPv4 маску сетевого интерфейса. Значение по + умолчанию <literal>255.255.255.0</literal>. + </para><para> + Эта опция не может использоваться с + опцией <option>--ip</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ipv6=<replaceable>IPv6-адрес</replaceable></option></term> + <listitem><para> + Задает IPv6 адрес сетевого интерфейса. + </para><para> + Эта опция не может использоваться с опциями + <option>--dhcp</option>, <option>--ip</option> + и <option>--netmask</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--netmasklengthv6=<replaceable>длина</replaceable></option></term> + <listitem><para> + Задает длину сетевого интерфейса IPv6. Значение по + умолчанию <literal>64</literal>. + </para><para> + Можно использовать эту опцию только с + опцией <option>--ipv6</option>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-hostonlyif-create"> + <title>Создать сетевой интерфейс в хост-системе</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage hostonlyif create</command> создает + новый интерфейс сети хоста в операционной сети хоста (ОС). + Имя сетевого интерфейса в форме + <literal>vboxnet</literal><replaceable>N</replaceable>, где + <replaceable>N</replaceable> это экземпляр интерфейса. Эта + команда должна запускаться перед тем, как подключать виртуальные + машины (ВМ) к сети хоста. + </para> + </refsect2> + <refsect2 id="vboxmanage-hostonlyif-remove"> + <title>Удалить сетевой интерфейс из хост-системы</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage hostonlyif remove</command> + удаляет указанный интерфейс сети хоста из ОС хоста. + </para> + <variablelist> + <varlistentry> + <term><replaceable>имя-интерфейса</replaceable></term> + <listitem><para> + Задает имя сетевого интерфейса. Имя в форме + <literal>vboxnet</literal><replaceable>N</replaceable>, + где <replaceable>N</replaceable> - это экземпляр + интерфейса. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда создает новый интерфейс сети хоста. + </para> +<screen>$ VBoxManage hostonlyif create +0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100% +Интерфейс 'vboxnet2' создан успешно</screen> + <para> + Следующая команда настраивает адрес IPv4 для интерфейса + сети хоста <literal>vboxnet2</literal>. + </para> +<screen>$ VBoxManage hostonlyif ipconfig vboxnet2 --ip 10.0.2.18</screen> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-hostonlynet.xml b/doc/manual/ru_RU/man_VBoxManage-hostonlynet.xml new file mode 100644 index 00000000..ee1ee506 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-hostonlynet.xml @@ -0,0 +1,164 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage hostonlynet +--> +<!-- + Copyright (C) 2021-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-hostonlynet" lang="en"> + + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage hostonlynet</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-hostonlynet</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-hostonlynet</refname> + <refpurpose>управление сетью хоста</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-hostonlynet-add"> + <command>VBoxManage hostonlynet add</command> + <arg choice="req">--name=<replaceable>имя-сети</replaceable></arg> + <arg choice="opt">--id=<replaceable>id-сети</replaceable></arg> + <arg choice="req">--netmask=<replaceable>маска</replaceable></arg> + <arg choice="req">--lower-ip=<replaceable>адрес</replaceable></arg> + <arg choice="req">--upper-ip=<replaceable>адрес</replaceable></arg> + <group choice="opt"> + <arg choice="plain">--enable</arg> + <arg choice="plain">--disable</arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-hostonlynet-modify"> + <command>VBoxManage hostonlynet modify</command> + <group choice="req"> + <arg choice="plain">--name=<replaceable>имя-сети</replaceable></arg> + <arg choice="plain">--id=<replaceable>id-сети</replaceable></arg> + </group> + <arg choice="opt">--lower-ip=<replaceable>адрес</replaceable></arg> + <arg choice="opt">--upper-ip=<replaceable>адрес</replaceable></arg> + <arg choice="opt">--netmask=<replaceable>маска</replaceable></arg> + <group choice="opt"> + <arg choice="plain">--enable</arg> + <arg choice="plain">--disable</arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-hostonlynet-remove"> + <command>VBoxManage hostonlynet remove</command> + <group choice="req"> + <arg choice="plain">--name=<replaceable>имя-сети</replaceable></arg> + <arg choice="plain">--id=<replaceable>id-сети</replaceable></arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + + <para> + Команда <command>hostonlynet</command> позволяет управлять сетями + хоста. + </para> + + <refsect2 id="vboxmanage-hostonlynet-common-options"> + <title>Общие параметры</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> Все подкоманды <command>hostonlynet</command> оперируют над + сетью хоста, идентифицируемой через ее имя или UUID:</para> + <variablelist> + <varlistentry> + <term>--name=<replaceable>имя-сети</replaceable></term> + <listitem><para>Имя сети хоста. Его можно увидеть в поле + VBoxNetworkName вывода команды + <command>VBoxManage list hostonlynets</command>. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--id=<replaceable>id-сети</replaceable></term> + <listitem><para>UUID сети хоста. Если не указан при добавлении + новой сети, то будет сгенерирован автоматически. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-hostonlynet-add"> + <title>hostonlynet add</title> + <remark role="help-copy-synopsis"/> + <para> + Добавляет новую сеть хоста. + </para> + <para> + Опции для настройки сети хоста: + </para> + <variablelist> + <varlistentry> + <term><option>--netmask=<replaceable>маска</replaceable></option></term> + <listitem><para>Сетевая маска. Обычно 255.255.255.0.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--lower-ip=<replaceable>адрес</replaceable></option>, <option>--upper-ip=<replaceable>адрес</replaceable></option></term> + <listitem><para> Диапазон IP адресов, распределяемых через DHCP. + Верхняя границы включается, тогда как нижняя - нет, поэтому + верхний адрес будет также распределен клиентам, тогда как + нижний используется самим хостом.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--enable</option>, --disable</term> + <listitem><para>Должная ли сеть хоста быть включена или выключена. Если не указано, + сеть создается во включенном состоянии.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-hostonlynet-modify"> + <title>hostonlynet modify</title> + <remark role="help-copy-synopsis"/> + <para> + Команда модифицирует существующую конфигурацию сети хоста. Она принимает те же + опции что и команда <command>add</command>. + </para> + </refsect2> + + <refsect2 id="vboxmanage-hostonlynet-remove"> + <title>hostonlynet remove</title> + <remark role="help-copy-synopsis"/> + <para> + Удаляет указанную сеть хоста. + </para> + </refsect2> + + </refsect1> + +</refentry> + diff --git a/doc/manual/ru_RU/man_VBoxManage-import.xml b/doc/manual/ru_RU/man_VBoxManage-import.xml new file mode 100644 index 00000000..91d60d97 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-import.xml @@ -0,0 +1,456 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage import +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-import" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage import</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-import</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-import</refname> + <refpurpose>импорт виртуальной конфигурации в формате OVF или из облачной службы и создание виртуальной машины</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-import-ovf"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage import</command> + <group choice="req"> + <arg choice="plain"><replaceable>имя-ovf</replaceable></arg> + <arg choice="plain"><replaceable>имя-ova</replaceable></arg> + </group> + <arg>--dry-run</arg> + <arg>--options=<group choice="plain"> + <arg choice="plain">keepallmacs</arg> + <arg choice="plain">keepnatmacs</arg> + <arg choice="plain">importtovdi</arg> + </group></arg> + <arg>--vsys=<replaceable>n</replaceable></arg> + <arg>--ostype=<replaceable>тип-ос</replaceable></arg> + <arg>--vmname=<replaceable>имя</replaceable></arg> + <arg>--settingsfile=<replaceable>файл</replaceable></arg> + <arg>--basefolder=<replaceable>папка</replaceable></arg> + <arg>--group=<replaceable>группа</replaceable></arg> + <arg>--memory=<replaceable>МБ</replaceable></arg> + <arg>--cpus=<replaceable>n</replaceable></arg> + <arg>--description=<replaceable>текст</replaceable></arg> + <arg>--eula=<group choice="plain"> + <arg choice="plain">show</arg> + <arg choice="plain">accept</arg> + </group></arg> + <arg>--unit=<replaceable>n</replaceable></arg> + <arg>--ignore</arg> + <arg>--scsitype=<group choice="plain"> + <arg choice="plain">BusLogic</arg> + <arg choice="plain">LsiLogic</arg> + </group></arg> + <!-- <arg>--controller=<replaceable>n</replaceable></arg> --> + <arg>--disk=<replaceable>путь</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-import-cloud"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage import</command> + <arg choice="plain">OCI://</arg> + <arg choice="plain">--cloud</arg> + <arg>--ostype=<replaceable>тип-ос</replaceable></arg> + <arg>--vmname=<replaceable>имя</replaceable></arg> + <arg>--basefolder=<replaceable>папка</replaceable></arg> + <arg>--memory=<replaceable>МБ</replaceable></arg> + <arg>--cpus=<replaceable>n</replaceable></arg> + <arg>--description=<replaceable>текст</replaceable></arg> + <arg choice="req">--cloudprofile=<replaceable>профиль</replaceable></arg> + <arg choice="req">--cloudinstanceid=<replaceable>id</replaceable></arg> + <arg>--cloudbucket=<replaceable>корзина</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage import</command> импортирует виртуальную + конфигурацию из формата OVF или из облачной службы, например &oci;. + Импорт производится путем копирования образов виртуальных дисков + (по умолчанию в формает VMDK образа) и создания виртуальных машин (ВМ) + в &product-name;. Смотрите <xref linkend="ovf" />. + </para> + <para> + Необходимо указать путь к OVF файлу или OVA архиву в качестве входных + данных или заполнитель для облачного варианта. В случае OVF конфигураций, + убедитесь, что все образы дисков в той же директории, что и OVF файл. + </para> + <para> + Обратите внимание, что любые опции, указываемые для управления + импортированной виртуальной конфигурацией или для изменения + параметров импорта зависят от содержимого файла OVF или от + информации из облачной службы. + </para> + <para> + Перед использованием операции импорта для создания ВМ, произведите + пробный запуск для проверки корректности вашей конфигурации. Это + полезно с конфигурациями OVF и OVA, потому что в случае с облачной + службой, даже при пробном запуске необходимо произвести достаточно + много действий, занимающих ощутимое время. + </para> + <para> + Импорт из облачной службы загружает временный файл, содержащий и + загрузочный образ и некоторые метаданные, описывающие детали + экземпляра ВМ. Временный файл удаляется после успешного импорта. + </para> + <refsect2> + <title>Общие параметры</title> + <variablelist> + <varlistentry> + <term><replaceable>имя-ovf</replaceable> | <replaceable>имя-ova</replaceable></term> + <listitem><para> + Задает имя файла OVF или архив OVA, описывающий конфигурацию. + В случае облака, это обычно фиксированная строка, такая как + <literal>OCI://</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dry-run</option></term> + <!-- Does this option really work for cloud import? --> + <listitem><para> + Производит пробный запуск команды <command>VBoxManage + import</command> перед проведением реальной операции + импорта. Операция пробного запуска делает следующее: + </para><itemizedlist> + <listitem><para> + Выводит описание содержимого конфигурации, основанное + на указанном OVF или OVA файле. + </para></listitem> + <listitem><para> + Показывает, как конфигурация могла быть импортирована + в &product-name;. В дополнение, вывод показывает все + опции, которые можно использовать для изменения + поведения импорта. + </para></listitem> + </itemizedlist><para> + Краткая форма этой опции <option>-n</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--options=keepallmacs | keepnatmacs | importtovdi</option></term> + <!-- Does this option really work for cloud import? --> + <listitem><para> + Позволяет подстроить операцию импорта. + </para><para> + Допустимые аргументы нижеследующие: + </para><itemizedlist> + <listitem><para> + <literal>keepallmacs</literal>: Указывает, что + MAC адреса каждой виртуальной сетевой карты + остаются неизменными. + </para></listitem> + <listitem><para> + <literal>keepnatmacs</literal>: Указывает, что + MAC адреса каждой виртуальной сетевой карты + остаются неизменными если тип сети - NAT. + </para></listitem> + <listitem><para> + <literal>importtovdi</literal>: Указывает, что + все новые образы дисков в формате файла VDI. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--ostype=<replaceable>тип-ос</replaceable></option></term> + <listitem><para> + Задает информацию о гостевой операционной системе (ОС) для + ВМ. Используйте команду <command>VBoxManage list ostypes</command> + для отображения идентификаторов типов ОС. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vmname=<replaceable>имя</replaceable></option></term> + <listitem><para> + Задает имя ВМ в &product-name;. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--basefolder=<replaceable>папка</replaceable></option></term> + <!-- Does this option really work for cloud import? --> + <listitem><para> + Задает папку, где сохраняются файлы импортированной ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--memory=<replaceable>МБ</replaceable></option></term> + <listitem><para> + Задает размер памяти в мегабайтах в импортированной ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpus=<replaceable>n</replaceable></option></term> + <listitem><para> + Задает количество ЦПУ в импортированной ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--description=<replaceable>текст</replaceable></option></term> + <listitem><para> + Задает текст описания, видимый в графическом и командном + интерфейсе при проверке деталей ВМ. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-import-ovf"> + <title>Опции импорта OVF / OVA</title> + <para> + Следующие опции предназначены для импорта виртуальной конфигурации + в форматах OVF или OVA. Такие конфигурации могут содержать один или + несколько ВМ. Поэтому требуется указать, какую конфигурацию ВМ надо + подстроить если вы хотите изменить ее. Смотрите + <xref linkend="ovf-import-appliance" />. + </para> + <remark role="help-copy-synopsis"/> + <variablelist> + <varlistentry> + <term><option>--vsys=<replaceable>n</replaceable></option></term> + <listitem><para> + Задает индекс конкретной ВМ внутри конфигурации. Влияет + на нижеследующие опции. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unit=<replaceable>n</replaceable></option></term> + <listitem><para> + Задает индекс конкретного элемента ВМ внутри конфигурации. + Влияет на нижеследующие опции. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--settingsfile=<replaceable>файл</replaceable></option></term> + <listitem><para> + Задает имя файла настроек ВМ (с указанием пути или без), + который будет создан как часть импорта. Обычно, более + предпочтительный способ это переопределение имени ВМ через + <option>--vmname</option> и, если нужно, указание папки, + где надо создать ВМ, через <option>--basefolder</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--group=<replaceable>группа</replaceable></option></term> + <listitem><para> + Задает первичную группу импортированной ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--eula=show | accept</option></term> + <listitem><para> + Позволяет вам отобразить или принять условия лицензии ВМ + внутри конфигурации. + </para><para> + Допустимы следующие аргументы: + </para><itemizedlist> + <listitem><para> + <literal>show</literal>: Показывает лицензионное соглашение ВМ. + </para></listitem> + <listitem><para> + <literal>accepts</literal>: Принимает лицензионное соглашение ВМ. + Все ВМ в конфигурации, имеющие лицензию, требуют ее принятия, + иначе импорт закончится неудачей. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--ignore</option></term> + <listitem><para> + Игнорирует текущий элемент импортируемой ВМ, эффективно + удаляя связанное аппаратное обеспечение. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--scsitype=BusLogic | LsiLogic</option></term> + <listitem><para> + Позволяет выбрать тип SCSI контроллера текущего элемента + импортированной ВМ. + </para><para> + Допустимы следующие аргументы: + </para><itemizedlist> + <listitem><para> + <literal>BusLogic</literal>: Использует SCSI контроллер + типа BusLogic (очень старый). + </para></listitem> + <listitem><para> + <literal>LsiLogic</literal>: Использует SCSI контроллер + типа LsiLogic (более современный). + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-import-cloud"> + <title>Опции импорта из облака</title> + <para> + Следующие опции предназначены для импорта экземпляра ВМ из + провайдера облачной службы. Они всегда имеют дело только + с одной ВМ. Смотрите <xref linkend="cloud-import-oci" />. + </para> + <remark role="help-copy-synopsis"/> + <variablelist> + <varlistentry> + <term><option>--cloud</option></term> + <listitem><para> + Указывает, что импорт должен быть из облака. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudprofile=<replaceable>профиль</replaceable></option></term> + <listitem><para> + Задает облачный профиль используемый для соединения с + провайдером облачной службы. Облачный профиль содержит + детали вашей учетной записи &oci;, такие как ваш OCID + пользователя и отпечаток вашего публичного ключа. У вас + должны быть требуемые права в &oci;, чтобы использовать + облачный профиль. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudinstanceid=<replaceable>id</replaceable></option></term> + <listitem><para> + Задает ID существующего экземпляра в облаке. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudbucket=<replaceable>корзина</replaceable></option></term> + <listitem><para> + Задает имя корзины, куда сохранять объекты, созданные из + экземпляра. В &oci;, корзина - это логический контейнер для + сохранения объектов. По умолчанию, используется первая + доступная корзина в облачном профиле. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + Следующий пример производит пробный запуск операции OVF импорта + примерной конфигурации, содержащей гостевую систему Windows 10: + </para> +<screen>$ VBoxManage import Windows10.ovf --dry-run +Интерпретация Windows10.ovf... +OK. +Виртуальная система 0: + 0: Предложенный тип ОС: "Windows10_64" + (изменить через "--vsys 0 --ostype <тип>"; используйте "list ostypes" для просмотра всех возможных значений) + 1: Предложенное имя ВМ "win10-appliance" + (изменить через "--vsys 0 --vmname <имя>") + 2: Предложенная группа ВМ "/" + (изменить через "--vsys 0 --group <группа>") + 3: Предложенное имя файла настроек ВМ "/home/user1/VirtualBox VMs/win10-appliance/win10-appliance.vbox" + (изменить через "--vsys 0 --settingsfile <имя файла>") + 4: Предложенная основная папка ВМ "/home/user1/VirtualBox VMs" + (изменить через "--vsys 0 --basefolder <путь>") + 5: Лицензионное соглашение + (показать через "--vsys 0 --eula show"; + принять через "--vsys 0 --eula accept") + 6: Число ЦПУ: 1 + (изменить через "--vsys 0 --cpus <n>") + 7: Размер памяти гостевой системы: 2048 MB (изменить через "--vsys 0 --memory <MB>") + 8: Аудио карта (конфигурация ожидает "ensoniq1371", может быть изменена при импорте) + (отключить через "--vsys 0 --unit 5 --ignore") + 9: USB контроллер + (отключить через "--vsys 0 --unit 6 --ignore") +10: Сетевой адаптер: ориг. сетевой мост, конфиг. 2, экстра тип=сетевой мост +11: Флоппи + (отключить через "--vsys 0 --unit 8 --ignore") +12: SCSI контроллер, тип BusLogic + (изменить через "--vsys 0 --unit 9 --scsitype {BusLogic|LsiLogic}"; + отключить через "--vsys 0 --unit 9 --ignore") +13: IDE контроллер, тип PIIX4 + (отключить через "--vsys 0 --unit 10 --ignore") +14: Образ жесткого диска: образ источника=Windows10.vmdk, + путь назначения=/home/user1/disks/Windows10.vmdk, контроллер=9;канал=0 + (изменить путь назначения через "--vsys 0 --unit 11 --disk <путь>"; + отключить через "--vsys 0 --unit 11 --ignore")</screen> + <para> + Вывод пробного запуска показывает и нумерует индивидуальные + элементы настройки описанные в файле + <filename>Windows10.ovf</filename>. Некоторые из них включают + информацию о том, как отключить или изменить настройку элемента. + </para> + <para> + Можно отключить многие элементы, используя опции <option>--vsys + <replaceable>X</replaceable> --unit <replaceable>Y</replaceable> + --ignore</option>. <replaceable>X</replaceable> - это номер + виртуальной системы. Значение равно <literal>0</literal> если + конфигурация содержит только одно описание виртуальной системы. + <replaceable>Y</replaceable> - это номер элемента конфигурации. + </para> + <para> + Элемент 1 в выводе команды примера указывает имя целевой машины. + Элементы 12 и 13 указывают контроллеры IDE и SCSI жестких дисков + соответственно. + </para> + <para> + Элемент 14 показывает образ жесткого диска и опцию + <option>--disk</option>, задающую путь назначения, где сохранять + образ. Значение по умолчанию задается в файле OVF. + </para> + <para> + Можно комбинировать несколько элементов для той же самой + виртуальной системы, путем указания того же самого значения + для опции <option>--vsys</option>. Например, используйте + следующую команду для импорта машины как описано в OVF, + кроме аудио карты и USB контроллера, и образ диска должен + сохраняться с другим именем. + </para> +<screen>$ VBoxManage import Windows10.ovf --vsys 0 --unit 8 --ignore \ + --unit 9 --ignore --unit 14 --disk Windows10_disk0.vmdk</screen> + <para> + Следующий пример иллюстрирует как импортировать ВМ из &oci;. Для поиска + экземпляров ВМ в &oci;, а также их ID, можно вывести список всех доступных + экземпляров через: + </para> +<screen>$ VBoxManage cloud --provider=OCI --profile=<replaceable>имя-облачного-профиля</replaceable> list instances</screen> + <para> + Когда ID известно, следующая команда импортирует экземпляр из &oci;: + </para> +<screen>$ VBoxManage import OCI:// --cloud --vmname OCI_FreeBSD_VM --memory 4000 \ + --cpus 3 --ostype FreeBSD_64 --cloudprofile "standard user" \ + --cloudinstanceid ocid1.instance.oc1.iad.abuwc... --cloudbucket myBucket</screen> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-list.xml b/doc/manual/ru_RU/man_VBoxManage-list.xml new file mode 100644 index 00000000..b2580b6a --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-list.xml @@ -0,0 +1,522 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage list +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-list" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage list</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-list</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-list</refname> + <refpurpose>просмотр системной информации и детали конфигурации ВМ</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-list"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage list</command> + <arg>--long</arg> + <arg>--sorted</arg> + <group> + <arg choice="plain">bridgedifs</arg> + <arg choice="plain">cloudnets</arg> + <arg choice="plain">cloudprofiles</arg> + <arg choice="plain">cloudproviders</arg> + <arg choice="plain">cpu-profiles</arg> + <arg choice="plain">dhcpservers</arg> + <arg choice="plain">dvds</arg> + <arg choice="plain">extpacks</arg> + <arg choice="plain">floppies</arg> + <arg choice="plain">groups</arg> + <arg choice="plain">hddbackends</arg> + <arg choice="plain">hdds</arg> + <arg choice="plain">hostcpuids</arg> + <arg choice="plain">hostdrives</arg> + <arg choice="plain">hostdvds</arg> + <arg choice="plain">hostfloppies</arg> + <arg choice="plain">hostinfo</arg> + <arg choice="plain">hostonlyifs</arg> + <arg choice="plain">hostonlynets</arg> + <arg choice="plain">intnets</arg> + <arg choice="plain">natnets</arg> + <arg choice="plain">ostypes</arg> + <arg choice="plain">runningvms</arg> + <arg choice="plain">screenshotformats</arg> + <arg choice="plain">systemproperties</arg> + <arg choice="plain">usbfilters</arg> + <arg choice="plain">usbhost</arg> + <arg choice="plain">vms</arg> + <arg choice="plain">webcams</arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Подкоманды <command>VBoxManage list</command> позволяют получить + информацию о ПО &product-name;, ВМ и соответствующих службах, + созданных вами. + </para> + <refsect2 id="vboxmanage-list-common-options"> + <title>Общие настройки</title> + <variablelist> + <varlistentry> + <term><option>--long</option></term> + <listitem><para> + Показывает детальную информацию по каждому элементу, + если она доступна. Краткая форма этой опции: + <option>-l</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--sorted</option></term> + <listitem><para> + Сортирует элементы детального списка по алфавиту. + Краткая форма этой опции: <option>-s</option>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-list-bridgedifs"> + <title>Отображение сетевых интерфейсов типа "Сетевой мост" в хост-системе</title> + <cmdsynopsis id="synopsis-vboxmanage-list-bridgedifs"> + <command>VBoxManage list</command> + <arg choice="plain">bridgedifs</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list bridgedifs</command> отображает + интерфейсы типа "сетевой мост", доступные на данный момент + в системе хоста. Вывод показывает детальную информацию о конфигурации + каждого интерфейса. Смотрите <xref linkend="networkingdetails"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-cloudnets"> + <title>Отображение облачных сетевых интерфейсов</title> + <cmdsynopsis id="synopsis-vboxmanage-list-cloudnets"> + <command>VBoxManage list</command> + <arg choice="plain">cloudnets</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list cloudnets</command> отображает + сконфигурированные облачные сетевые интерфейсы. Облачный сетевой + интерфейс обеспечивает соединение между локальной ВМ и облачной + сетью. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-cloudprofiles"> + <title>Отображение облачных профилей</title> + <cmdsynopsis id="synopsis-vboxmanage-list-cloudprofiles"> + <command>VBoxManage list</command> + <arg choice="plain">cloudprofiles</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list cloudprofiles</command> отображает + сконфигурированные облачные профили. Облачный профиль содержит + настройки для учетной записи службы облака. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-cloudproviders"> + <title>Отображение облачных провайдеров</title> + <cmdsynopsis id="synopsis-vboxmanage-list-cloudproviders"> + <command>VBoxManage list</command> + <arg choice="plain">cloudproviders</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list cloudproviders</command> показывает + облачных провайдеров, поддерживаемых &product-name;. + Примером облачного провайдера является Oracle Cloud Infrastructure. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-cpu-profiles"> + <title>Отображение известных профилей ЦПУ</title> + <cmdsynopsis id="synopsis-vboxmanage-list-cpu-profiles"> + <command>VBoxManage list</command> + <arg choice="plain">cpu-profiles</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list cpu-profiles</command> отображает + ЦПУ профили, известные в &product-name;. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-dhcpservers"> + <title>Отображение DHCP серверов в хост-системе</title> + <cmdsynopsis id="synopsis-vboxmanage-list-dhcpservers"> + <command>VBoxManage list</command> + <arg choice="plain">dhcpservers</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list dhcpservers</command> отображает + DHCP серверы, доступные в хост-системе. Вывод показывает + детальную информацию о конфигурации каждого DHCP сервера. + Смотрите <xref linkend="networkingdetails"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-dvds"> + <title>Отображение образов виртуальных дисков DVD</title> + <cmdsynopsis id="synopsis-vboxmanage-list-dvds"> + <command>VBoxManage list</command> + <arg choice="plain">dvds</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list dvds</command> отображает + информацию об образах виртуальных дисков DVD, используемых + в данный момент в ПО &product-name;. Для каждого образа + вывод показывает все настройки, UUID, назначенные образу + в &product-name; и все файлы связанные с образом. + </para> + <para> + Эта команда выполняет ту же функцию, что и Менеджер виртуальных + носителей. Смотрите <xref linkend="virtual-media-manager"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-extpacks"> + <title>Отображение установленных пакетов расширения &product-name;</title> + <cmdsynopsis id="synopsis-vboxmanage-list-extpacks"> + <command>VBoxManage list</command> + <arg choice="plain">extpacks</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list extpacks</command> показывает + все пакеты расширения &product-name;, установленные в системе + на данный момент. Смотрите <xref linkend="intro-installing"/> и + <xref linkend="vboxmanage-extpack"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-floppies"> + <title>Отображение образов виртуальных флоппи дисков</title> + <cmdsynopsis id="synopsis-vboxmanage-list-floppies"> + <command>VBoxManage list</command> + <arg choice="plain">floppies</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list floppies</command> отображает + информацию об образах флоппи дисков, используемых в &product-name; + на данный момент. Для каждого образа вывод показывает все настройки, + UUID, назначенные образу в &product-name; и все файлы связанные + с образом. + </para> + <para> + Эта команда выполняет ту же функцию, что и Менеджер виртуальных + носителей. Смотрите <xref linkend="virtual-media-manager"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-groups"> + <title>Отображение групп виртуальных машин</title> + <cmdsynopsis id="synopsis-vboxmanage-list-groups"> + <command>VBoxManage list</command> + <arg choice="plain">groups</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list groups</command> показывает + все группы ВМ. Смотрите <xref linkend="gui-vmgroups"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hddbackends"> + <title>Отображение бэкендов виртуальных дисков</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hddbackends"> + <command>VBoxManage list</command> + <arg choice="plain">hddbackends</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list hddbackends</command> отображает + все известные бэкенды виртуальных дисков ПО &product-name; + Для каждого такого формата, таких как VDI, VMDK или RAW, эта + команда показывает конфигурацию и возможности бэкенда. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hdds"> + <title>Отображение образов виртуальных жестких дисков</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hdds"> + <command>VBoxManage list</command> + <arg choice="plain">hdds</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list hdds</command> отображает + информацию об образах виртуальных жестких дисков, которые + используются ПО &product-name; на данный момент. Для каждого + образа вывод показывает все настройки, UUID, назначенные образу + в &product-name; и все файлы связанные с образом. + </para> + <para> + Эта команда выполняет ту же функцию, что и Менеджер виртуальных + носителей. Смотрите <xref linkend="virtual-media-manager"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hostcpuids"> + <title>Отображение информации CPUID для ЦПУ хост-системы</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hostcpuids"> + <command>VBoxManage list</command> + <arg choice="plain">hostcpuids</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list hostcpuids</command> отображает + информацию CPUID для каждого ЦПУ хост-системы. Используйте эту + информацию для более тщательного анализа возможностей + виртуализации в хост-системе. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hostdrives"> + <title>Отображение дисков в хост-системе</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hostdrives"> + <command>VBoxManage list</command> + <arg choice="plain">hostdrives</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list hostdrives</command> отображает + диски в хост-системе, потенциально полезные для создания образов + VMDK raw дисков. Каждый элемент включает имя, используемое для + ссылки на них из &product-name;. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hostdvds"> + <title>Отображение DVD дисков в хост-системе</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hostdvds"> + <command>VBoxManage list</command> + <arg choice="plain">hostdvds</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list hostdvds</command> отображает + DVD диски хост-системы. Каждый элемент включает имя, используемое + для доступа к ним из &product-name;. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hostfloppies"> + <title>Отображение флоппи дисков в хост-системе</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hostfloppies"> + <command>VBoxManage list</command> + <arg choice="plain">hostfloppies</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list hostfloppies</command> + отображает флоппи диски в хост-системе. Каждый элемент + включает имя, используемое для доступа к ним из &product-name;. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hostinfo"> + <title>Отображение информации о хост-системе</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hostinfo"> + <command>VBoxManage list</command> + <arg choice="plain">hostinfo</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list hostinfo</command> отображает + информацию о хост-системе. Вывод включает информацию о ЦПУ, + памяти и версии ОС. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hostonlyifs"> + <title>Отображение сетевых интерфейсов виртуальной сети хоста</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hostonlyifs"> + <command>VBoxManage list</command> + <arg choice="plain">hostonlyifs</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list hostonlyifs</command> отображает + интерфейсы виртуальной сети хоста, доступные в системе на данный + момент. Вывод показывает детальную информацию о конфигурации + каждого интерфейса. Смотрите <xref linkend="networkingdetails"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hostonlynets"> + <title>Отображение виртуальных сетей хоста</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hostonlynets"> + <command>VBoxManage list</command> + <arg choice="plain">hostonlynets</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list hostonlynets</command> отображает + сконфигурированные виртуальные сети хоста. Виртуальная сеть хоста + обеспечивает соединение между хостом и локальными ВМ. Смотрите + <xref linkend="networkingdetails"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-intnets"> + <title>Отображение внутренних сетей</title> + <cmdsynopsis id="synopsis-vboxmanage-list-intnets"> + <command>VBoxManage list</command> + <arg choice="plain">intnets</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list intnets</command> показывает + информацию о внутренних сетях. Смотрите + <xref linkend="networkingdetails"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-natnets"> + <title>Отображение интерфейсов сетей NAT в хост-системе</title> + <cmdsynopsis id="synopsis-vboxmanage-list-natnets"> + <command>VBoxManage list</command> + <arg choice="plain">natnets</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list natnets</command> отображает + интерфейсы сетей NAT, доступные в хост-системе на данный момент. + Смотрите <xref linkend="networkingdetails"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-ostypes"> + <title>Отображение гостевых операционных систем</title> + <cmdsynopsis id="synopsis-vboxmanage-list-ostypes"> + <command>VBoxManage list</command> + <arg choice="plain">ostypes</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list ostypes</command> отображает + все гостевые операционные системы, известные ПО &product-name;. + Каждый элемент включает идентификатор, описание, идентификатор + семейства, описание семейства и имеет ли ОС 64 битную поддержку. + </para> + <para> + Можно изспользовать эти идентификаторы с командой <command>VBoxManage + modifyvm</command>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-runningvms"> + <title>Отображение работающих виртуальных машин</title> + <cmdsynopsis id="synopsis-vboxmanage-list-runningvms"> + <command>VBoxManage list</command> + <arg choice="plain">runningvms</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list runningvms</command> отображает + все виртуальные машины (ВМ), работающие на данный момент. По + умолчанию она показывает компактный список, содержащий имя и + UUID каждой машины. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-screenshotformats"> + <title>Отображение доступных форматов снимков экрана</title> + <cmdsynopsis id="synopsis-vboxmanage-list-screenshotformats"> + <command>VBoxManage list</command> + <arg choice="plain">screenshotformats</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list screenshotformats</command> показывает + список доступных форматов снимков экрана. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-systemproperties"> + <title>Отображение системных свойств</title> + <cmdsynopsis id="synopsis-vboxmanage-list-systemproperties"> + <command>VBoxManage list</command> + <arg choice="plain">systemproperties</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list systemproperties</command> показывает + большую коллекцию глобальных настроек &product-name; + и лимитов, таких как минимальный и максимальный размер RAM + гостевой системы, размер виртуального жесткого диска, настройки + папки и используемая в данный момент библиотека аутентификации. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-usbfilters"> + <title>Отображение зарегистрированных глобальных USB фильтров</title> + <cmdsynopsis id="synopsis-vboxmanage-list-usbfilters"> + <command>VBoxManage list</command> + <arg choice="plain">usbfilters</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list usbfilters</command> отображает + все глобальные USB фильтры зарегистрированные в &product-name; + и показывает параметры фильтра. Глобальные USB фильтры - это + фильтры для устройств, доступные всем виртуальным машинам. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-usbhost"> + <title>Отображение USB устройств в хост-системе</title> + <cmdsynopsis id="synopsis-vboxmanage-list-usbhost"> + <command>VBoxManage list</command> + <arg choice="plain">usbhost</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list usbhost</command> отображает + информацию об USB устройствах, подключенных к хост-системе. + Вывод включает информацию, которую можно использовать для + построения USB фильтров и показывает, используется ли + устройство хост-системой на данный момент. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-vms"> + <title> Отображение виртуальных машин</title> + <cmdsynopsis id="synopsis-vboxmanage-list-vms"> + <command>VBoxManage list</command> + <arg choice="plain">vms</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list vms</command> отображает + все виртуальные машины (ВМ), зарегистрированные в &product-name; + на данный момент. По умолчанию эта команда показывает компактный + список, включающий имя и UUID каждой машины. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-webcams"> + <title>Отображение вебкамер, подключенных к работающей виртуальной машине</title> + <cmdsynopsis id="synopsis-vboxmanage-list-webcams"> + <command>VBoxManage list</command> + <arg choice="plain">webcams</arg> + </cmdsynopsis> + <para> + Команда <command>VBoxManage list webcams</command> показывает + список вебкамер, подключенных к работающей ВМ. + </para> + <para> + Вывод состоит из списка абсолютных путей или псевдонимов, + используемых для подключения вебкамер к ВМ, используя команду + <command>VBoxManage webcam attach</command>. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда показывает группы ВМ, сконфигурированные в + &product-name;. + </para> +<screen>$ VBoxManage list groups +"/Linux-VMs" +"/Windows-VMs"</screen> + <para> + Следующая команда показывает работающие на данный момент ВМ. + </para> +<screen>$ VBoxManage list runningvms +"ol7" {<replaceable>ol7-UUID</replaceable>} +"win8" {<replaceable>win8-UUID</replaceable>}</screen> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-mediumio.xml b/doc/manual/ru_RU/man_VBoxManage-mediumio.xml new file mode 100644 index 00000000..880a9e52 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-mediumio.xml @@ -0,0 +1,179 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage mediumio +--> +<!-- + Copyright (C) 2018-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-mediumio" lang="en"> + + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage mediumio</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-mediumio</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-mediumio</refname> + <refpurpose>доступ к содержимому носителя</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-mediumio-formatfat"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage mediumio</command> + <group choice="req"> + <arg choice="plain">--disk=<replaceable>uuid|имя-файла</replaceable></arg> + <arg choice="plain">--dvd=<replaceable>uuid|имя-файла</replaceable></arg> + <arg choice="plain">--floppy=<replaceable>uuid|имя-файла</replaceable></arg> + </group> + <arg>--password-file=<replaceable>-|имя-файла</replaceable></arg> + <arg choice="plain">formatfat</arg> + <arg>--quick</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-mediumio-cat"> + <command>VBoxManage mediumio</command> + <group choice="req"> + <arg choice="plain">--disk=<replaceable>uuid|имя-файла</replaceable></arg> + <arg choice="plain">--dvd=<replaceable>uuid|имя-файла</replaceable></arg> + <arg choice="plain">--floppy=<replaceable>uuid|имя-файла</replaceable></arg> + </group> + <arg>--password-file=<replaceable>-|имя-файла</replaceable></arg> + <arg choice="plain">cat</arg> + <arg>--hex</arg> + <arg>--offset=<replaceable>смещение-байт</replaceable></arg> + <arg>--size=<replaceable>байты</replaceable></arg> + <arg>--output=<replaceable>-|имя-файла</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-mediumio-stream"> + <command>VBoxManage mediumio</command> + <group choice="req"> + <arg choice="plain">--disk=<replaceable>uuid|имя-файла</replaceable></arg> + <arg choice="plain">--dvd=<replaceable>uuid|имя-файла</replaceable></arg> + <arg choice="plain">--floppy=<replaceable>uuid|имя-файла</replaceable></arg> + </group> + <arg>--password-file=<replaceable>-|имя-файла</replaceable></arg> + <arg choice="plain">stream</arg> + <arg>--format=<replaceable>формат-образа</replaceable></arg> + <arg>--variant=<replaceable>вариант-образа</replaceable></arg> + <arg>--output=<replaceable>-|имя-файла</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + + <refsect2 id="vboxmanage-mediumio-common-options"> + <title>Общие параметры</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>Все подкоманды <command>mediumio</command> оперируют носителем, который должен быть указан вместе с паролем + шифрования (необязательно). Следующие общие опции могут быть помещены перед или после подкоманд:</para> + <variablelist> + <varlistentry> + <term>--disk=<replaceable>uuid|имя-файла</replaceable></term> + <listitem><para>UUID или имя файла образа жесткого диска, например VDI, VMDK, VHD, и т.д.</para></listitem> + </varlistentry> + <varlistentry> + <term>--dvd=<replaceable>uuid|имя-файла</replaceable></term> + <listitem><para>UUID или имя файла образа DVD, например ISO, DMG, CUE.</para></listitem> + </varlistentry> + <varlistentry> + <term>--floppy=<replaceable>uuid|имя-файла</replaceable></term> + <listitem><para>UUID или имя файла образа флоппи, например IMG.</para></listitem> + </varlistentry> + <varlistentry> + <term>--password-file=<replaceable>-|имя-файла</replaceable></term> + <listitem><para>Имя файла, содержащего пароль шифрования носителя. Если указана опция <option>-</option>, + пароль читается из стандартного потока ввода. </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-mediumio-formatfat"> + <title>mediumio formatfat</title> + <remark role="help-copy-synopsis"/> + <para> + Форматирует носитель флоппи диска файловой системой FAT. Эта команда удаляет + содержимое носителя. + </para> + <variablelist> + <varlistentry> + <term><option>--quick</option></term><listitem><para>Быстрое форматирование носителя.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-mediumio-cat"> + <title>mediumio cat</title> + <remark role="help-copy-synopsis"/> + <para> + Сбрасывает содержимое носителя в стандартный поток вывода или в указанный файл. + </para> + <variablelist> + <varlistentry> + <term><option>--hex</option></term><listitem><para>Сбросить как hex байты.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--offset</option></term><listitem><para>Смещение в байтах с начала носителя, откуда начинать сброс дампа.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--size</option></term><listitem><para>Количество байтов для сброса.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--output</option></term> + <listitem><para>Имя выходного файла. Как обычно, <option>-</option> подразумевает стандартный поток вывода.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-mediumio-stream"> + <title>mediumio stream</title> + <remark role="help-copy-synopsis"/> + <para> + Преобразует носитель в потоковый формат и сбрасывает его в указанный выход. + </para> + <variablelist> + <varlistentry> + <term><option>--format</option></term><listitem><para>Формат образа назначения.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--variant</option></term><listitem><para>Вариант носителя назначения.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--output</option></term> + <listitem><para>Имя выходного файла. Как обычно, <option>-</option> подразумевает стандартный поток вывода.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsect1> + +</refentry> + diff --git a/doc/manual/ru_RU/man_VBoxManage-mediumproperty.xml b/doc/manual/ru_RU/man_VBoxManage-mediumproperty.xml new file mode 100644 index 00000000..2fe23724 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-mediumproperty.xml @@ -0,0 +1,219 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage mediumproperty +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-mediumproperty" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage mediumproperty</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-mediumproperty</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-mediumproperty</refname> + <refpurpose>управлять свойствами носителя</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-mediumproperty-set"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage mediumproperty</command> + <group> + <arg choice="plain">disk</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">floppy</arg> + </group> + <arg choice="plain">set</arg> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-файла</replaceable></arg> + </group> + <arg choice="req"><replaceable>имя-свойства</replaceable></arg> + <arg choice="req"><replaceable>значение-свойства</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-mediumproperty-get"> + <command>VBoxManage mediumproperty</command> + <group> + <arg choice="plain">disk</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">floppy</arg> + </group> + <arg choice="plain">get</arg> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-файла</replaceable></arg> + </group> + <arg choice="req"><replaceable>имя-свойства</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-mediumproperty-delete"> + <command>VBoxManage mediumproperty</command> + <group> + <arg choice="plain">disk</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">floppy</arg> + </group> + <arg choice="plain">delete</arg> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-файла</replaceable></arg> + </group> + <arg choice="req"><replaceable>имя-свойства</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage mediumproperty</command> позволяет + установить, получить или удалить свойство носителя. + </para> + <refsect2 id="vboxmanage-mediumproperty-set"> + <title>Установить свойство носителя</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage mediumproperty set</command> + позволяет установить свойство носителя. + </para> + <variablelist> + <varlistentry> + <term><literal>disk | dvd | floppy</literal></term> + <listitem><para> + Указывает тип носителя. Допустимые значения + <literal>disk</literal> (жесткий диск), + <literal>dvd</literal> или <literal>floppy</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>имя-файла</replaceable></term> + <listitem><para> + Задает Универсальный Уникальный Идентификатор (UUID) + или абсолютный путь к носителю или образу. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>имя-свойства</replaceable></term> + <listitem><para> + Задает имя свойства. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>значение-свойства</replaceable></term> + <listitem><para> + Задает значение указанного свойства. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-mediumproperty-get"> + <title>Получить значение свойства носителя</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage mediumproperty get</command> + позволяет получить значение свойства носителя. + </para> + <variablelist> + <varlistentry> + <term><literal>disk | dvd | floppy</literal></term> + <listitem><para> + Задает тип носителя. Допустимые значения + <literal>disk</literal> (жесткий диск), + <literal>dvd</literal> или <literal>floppy</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>имя-файла</replaceable></term> + <listitem><para> + Указывает Универсальный Уникальный Идентификатор (UUID) + или абсолютный путь к носителю или образу. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>имя-свойства</replaceable></term> + <listitem><para> + Задает имя свойства. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-mediumproperty-delete"> + <title>Удалить свойство носителя</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage mediumproperty delete</command> + позволяет удалить свойство носителя. + </para> + <variablelist> + <varlistentry> + <term><literal>disk | dvd | floppy</literal></term> + <listitem><para> + Задает тип носителя. Допустимые значения + <literal>disk</literal> (жесткий диск), + <literal>dvd</literal> или <literal>floppy</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>имя-файла</replaceable></term> + <listitem><para> + Указывает Универсальный Уникальный Идентификатор (UUID) + или абсолютный путь к носителю или образу. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>имя-свойства</replaceable></term> + <listitem><para> + Задает имя свойства. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда устанавливает свойство, называемое + <literal>prop1</literal> в значение <literal>val1</literal> + для образа диска <filename>ol7.vdi</filename>. + </para> +<screen>$ VBoxManage mediumproperty disk set ol7.vdi prop1 val1</screen> + <para> + Следующая команда получает значение свойства, называемого + <literal>prop1</literal> образа диска <filename>ol7.vdi</filename>. + </para> +<screen>$ VBoxManage mediumproperty disk get ol7.vdi prop1</screen> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-metrics.xml b/doc/manual/ru_RU/man_VBoxManage-metrics.xml new file mode 100644 index 00000000..e7b36c47 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-metrics.xml @@ -0,0 +1,422 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage metrics +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-metrics" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage metrics</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-metrics</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-metrics</refname> + <refpurpose>мониторинг использования системных ресурсов</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-metrics-collect"> + <command>VBoxManage metrics collect</command> + <arg>--detach</arg> + <arg>--list</arg> + <arg>--period=<replaceable>секунды</replaceable></arg> + <arg>--samples=<replaceable>количество</replaceable></arg> + <group> + <arg choice="plain">*</arg> + <arg choice="plain">host</arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable> <arg><replaceable>список-метрик</replaceable></arg></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-metrics-disable"> + <command>VBoxManage metrics disable</command> + <arg>--list</arg> + <group> + <arg choice="plain">*</arg> + <arg choice="plain">host</arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable> <arg><replaceable>список-метрик</replaceable></arg></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-metrics-enable"> + <command>VBoxManage metrics enable</command> + <arg>--list</arg> + <group> + <arg choice="plain">*</arg> + <arg choice="plain">host</arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable> <arg><replaceable>список-метрик</replaceable></arg></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-metrics-list"> + <command>VBoxManage metrics list</command> + <group> + <arg choice="plain">*</arg> + <arg choice="plain">host</arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable> <arg><replaceable>список-метрик</replaceable></arg></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-metrics-query"> + <command>VBoxManage metrics query</command> + <group> + <arg choice="plain">*</arg> + <arg choice="plain">host</arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable> <arg><replaceable>список-метрик</replaceable></arg></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-metrics-setup"> + <command>VBoxManage metrics setup</command> + <arg>--list</arg> + <arg>--period <replaceable>секунды</replaceable></arg> + <arg>--samples <replaceable>количество</replaceable></arg> + <group> + <arg choice="plain">*</arg> + <arg choice="plain">host</arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable> <arg><replaceable>список-метрик</replaceable></arg></arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage metrics</command> позволяет наблюдать + за использованием системных ресурсов в хост-системе и в + виртуальных машинах (ВМ). Например, можно контролировать + определенную метрику, такую как процент времени, затрачиваемую + ЦПУ при выполнении в пользовательском режиме + (<literal>CPU/Load/User</literal>) в течение определенного + периода. + </para> + <para> + Пока она работает, процесс <command>VBoxSVC</command> собирает + и сохраняет данные указанной метрики внутри. Процесс + <command>VBoxSVC</command> завершает работу почти сразу после + закрытия всех ВМ и интерфейсов пользователя. Используйте команду + <command>VBoxManage metrics query</command> для получения данных + в любое время. + </para> + <para> + По умолчанию, метрики не собираются, пока не будет запущена + команда <command>VBoxManage metrics setup</command>, в которой + указывается интервал выборки в секундах и количество сохраняемых + метрик. + </para> + <para> + Заметим, что включить сбор метрик можно только для запущенных ВМ. + Собранные данные и настройки сбора данных для ВМ удаляются при + выключении ВМ. + </para> + <refsect2> + <title>Метрики</title> + <para> + У хоста и ВМ есть разные наборы соответствующих метрик, + которые можно отобразить через команду <command>VBoxManage + metrics list</command> + </para> + <para> + Каждая метрика представлена строкой состоящей из категории и + метрики. Опционально, строка метрик может включать любое из + следующих: подметрика, под-подметрика и агрегат. Строка + метрик имеет следующий формат: + </para> +<screen><replaceable>категория</replaceable>/<replaceable>метрика</replaceable>[/<replaceable>подметрика</replaceable>[/<replaceable>под-подметрика</replaceable>]][:<replaceable>агрегат</replaceable>]</screen> + <itemizedlist> + <listitem><para> + <replaceable>категория</replaceable> - это тип ресурса, + такой как <literal>CPU</literal>, <literal>RAM</literal>, + <literal>FS</literal>, <literal>Net</literal>. + </para></listitem> + <listitem><para> + <replaceable>метрика</replaceable> - это тип измерения, + связанной с категорией ресурса. Например, метрики + <literal>Load</literal> и <literal>MHz</literal> + связаны с категорией ресурса <literal>CPU</literal>. + </para></listitem> + <listitem><para> + <replaceable>подметрика</replaceable> - это опциональный + тип измерения, связанный с метрикой. Например, подметрики + <literal>User</literal>, <literal>Kernel</literal> и + <literal>Idle</literal> связаны с метрикой + <literal>Load</literal>. + </para></listitem> + <listitem><para> + <replaceable>под-подметрика</replaceable> - это опциональный + тип измерения связанный с подметрикой. Например, под-подметрики + <literal>Rx</literal> и <literal>Tx</literal> связаны с + подметрикой <literal>Rate</literal> категории ресурса + <literal>Net</literal>. Связанная метрика - это сетевой + интерфейс. + </para></listitem> + <listitem><para> + <replaceable>агрегат</replaceable> - это опциональная + функция для передачи минимального, максимального и среднего + значения измерений категории ресурса. Например, метрика + <literal>RAM/Usage/Free:min</literal> представляет + минимальное количество доступной памяти найденное во всех + сохраненных данных в хост-системе. + </para></listitem> + </itemizedlist> + <para> + По умолчанию, команды <command>VBoxManage metrics</command> + оперируют хост-системой и всеми ВМ и возвращают все метрики. + Можно опционально ограничить эти команды работой только по + хост-системе или только по определенной ВМ и возвращать + список одной или нескольких метрик. + </para> + </refsect2> + <refsect2 id="vboxmanage-metrics-common-options"> + <title>Общие параметры</title> + <variablelist> + <varlistentry> + <term><literal>*</literal> | <literal>host</literal> | <replaceable>имя-ВМ</replaceable></term> + <listitem><para> + Задает компонент для работы. По умолчанию, эта команда + работает по хост-системе и всем запущенным ВМ. + </para><para> + Если указать <literal>host</literal>, команда + <command>VBoxManage metrics</command> работает только по + хост-системе. Если указать звездочку (<literal>*</literal>), + команда работает по всем ВМ. Если указать имя ВМ, команда + <command>VBoxManage metrics</command> работает только + по этой ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>список-метрик</replaceable></term> + <listitem><para> + Задает список одной или нескольких метрик, разделенный + запятыми. + </para><para> + Формат метрик должен включать <replaceable>категорию</replaceable> + и <replaceable>метрику</replaceable> в строке, разделенную + слэшем. + </para><para> + Заметим, что команды <command>VBoxManage metrics + enable</command> и <command>VBoxManage metrics + disable</command> требуют указания метрик как параметров. + Метрики должны включать только категорию ресурса и саму + метрику, например <literal>CPU/Load</literal> и + <literal>RAM/Usage</literal>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-metrics-collect"> + <title>Сбор данных метрик</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage metrics collect</command> + собирает и выводит периодически данные, пока процесс не + будет остановлен нажатием Ctrl+C. + </para> + <variablelist> + <varlistentry> + <term><option>--detach</option></term> + <listitem><para> + Отключает сбор данных метрики, так что больше данных + не выводится. Использование этой опции равносильно + запуску команды <command>VBoxManage metrics setup</command>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--list</option></term> + <listitem><para> + Показывает какие метрики соответствуют указанному фильтру. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--period=<replaceable>секунды</replaceable></option></term> + <listitem><para> + Задает количество секунд ожидания между выборками + данных метрик. По умолчанию 1. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--samples=<replaceable>количество</replaceable></option></term> + <listitem><para> + Задает количество сохраняемых выборок данных метрик. + Для просмотра сохраненных данных используйте команду + <command>VBoxManage metrics query</command>. По + умолчанию 1. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-metrics-disable"> + <title>Отключить сбор данных метрик</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage metrics disable</command> + приостанавливает сбор данных. Эта команда не влияет ни на + свойства сбора данных, ни на сами собранные данные. Обратите + внимание, что указание подметрики в списке метрик не отключает + ее базовые метрики. + </para> + <para> + Заметим, что команда <command>VBoxManage metrics disable</command> + требует указания метрик как параметров. Метрики должны включать + только категорию ресурса и саму метрику, например + <literal>CPU/Load</literal> и <literal>RAM/Usage</literal>. + </para> + <variablelist> + <varlistentry> + <term><option>--list</option></term> + <listitem><para> + Показывает завершилась ли команда успешно как ожидалось. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-metrics-enable"> + <title>Включение сбора данных метрики</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage metrics enable</command> возобновляет + сбор данных после того, как он был приостановлен командой + <command>VBoxManage metrics disable</command>. Заметим, что + указание подметрики в списке метрик не включает его базовые + метрики. + </para> + <para> + В отличие от команды <command>VBoxManage metrics setup</command> + команда <command>VBoxManage metrics enable</command> не удаляет + предыдущие накопленные выборки для указанного набора объектов и + метрик. + </para> + <para> + Заметим, что команда <command>VBoxManage metrics enable</command> + требует указания метрик как параметров. Метрики должны включать + только категорию ресурса и саму метрику, например + <literal>CPU/Load</literal> и <literal>RAM/Usage</literal>. + </para> + <variablelist> + <varlistentry> + <term><option>--list</option></term> + <listitem><para> + Показывает, завершилась ли команда успешно как ожидалось. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-metrics-list"> + <title>Показать значения метрик</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage metrics list</command> показывает + доступные на текущий момент метрики. Обратите внимание, метрики, + относящиеся к ВМ, отображаются пока ВМ работает. + </para> + </refsect2> + <refsect2 id="vboxmanage-metrics-query"> + <title>Показать сохраненные данные метрики</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage metrics query</command> + получает и показывает сохраненные данные метрики. + </para> + <para> + Заметим, что команда <command>VBoxManage metrics query</command> + не удаляет и не сбрасывает сохраненные данные, но старые + выборки заменяются на новые в течение времени. + </para> + </refsect2> + <refsect2 id="vboxmanage-metrics-setup"> + <title>Настройка свойств сбора метрик</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage metrics setup</command> настраивает + свойства сбора метрик. + </para> + <para> + Заметим, что эта команда удаляет любые ранее собранные выборки + для указанного набора объектов и метрик. Для включения и отключения + сбора метрик без удаления данных используйте команды + <command>VBoxManage metrics enable</command> и + <command>VBoxManage metrics disable</command> соответственно. + </para> + <variablelist> + <varlistentry> + <term><option>--list</option></term> + <listitem><para> + Показывает какие метрики были изменены в качестве результата + выполнения команды. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--period=<replaceable>секунды</replaceable></option></term> + <listitem><para> + Задает количество секунд ожидания между выборками данных метрик. + По умолчанию 1. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--samples=<replaceable>количество</replaceable></option></term> + <listitem><para> + Задает количество сохраняемых выборок данных метрик. + Для просмотра сохраненных данных используйте команду + <command>VBoxManage metrics query</command>. По + умолчанию 1. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + Следующая команда включает сбор метрик использования + процессора и памяти хоста каждую секунду. Опция + <option>--samples</option> сохраняет пять последних + выборок. + </para> +<screen>$ VBoxManage metrics setup --period 1 --samples 5 host CPU/Load,RAM/Usage</screen> + <para> + Следующая команда показывает доступные метрики для хоста и ВМ: + </para> +<screen>$ VBoxManage metrics list</screen> + <para> + Заметим, что у хост-системы и ВМ разные наборы метрик. + </para> + <para> + Следующий пример показывает как запросить данные метрик о затраченном + времени ЦПУ в режимах пользователя и ядра для ВМ <literal>test</literal>: + </para> +<screen>$ VBoxManage metrics query test CPU/Load/User,CPU/Load/Kernel</screen> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-modifymedium.xml b/doc/manual/ru_RU/man_VBoxManage-modifymedium.xml new file mode 100644 index 00000000..911b25dc --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-modifymedium.xml @@ -0,0 +1,254 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage modifymedium +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-modifymedium" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage modifymedium</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-modifymedium</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-modifymedium</refname> + <refpurpose>изменяет характеристики существующего образа диска</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-modifymedium"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage modifymedium</command> + <group> + <arg choice="plain">disk</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">floppy</arg> + </group> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-файла</replaceable></arg> + </group> + <arg>--autoreset=on | off</arg> + <arg>--compact</arg> + <arg>--description=<replaceable>описание</replaceable></arg> + <arg>--move=<replaceable>путь</replaceable></arg> + <arg>--property=<replaceable>имя</replaceable>=[<replaceable>значение</replaceable>]</arg> + <arg>--resize=<replaceable>мегабайты</replaceable> | --resizebyte=<replaceable>байты</replaceable></arg> + <arg>--setlocation=<replaceable>путь</replaceable></arg> + <arg>--type=normal | writethrough | immutable | shareable | readonly | multiattach</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage modifymedium</command> позволяет + изменить характеристики существующего образа диска. + </para> + <note> + <para> + Для совместимости с более ранними версиями &product-name; + можно использовать команды <command>modifyvdi</command> и + <command>modifyhd</command>. + </para> + </note> + <variablelist> + <varlistentry> + <term>disk | dvd | floppy</term> + <listitem><para> + Задает тип носителя образа. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>имя-файла</replaceable></term> + <listitem><para> + Задает Универсальный Уникальный Идентификатор (UUID) или + путь к образу диска в файловой системе хоста. UUID можно + использовать, только если носитель зарегистрирован. + Используйте команду <command>VBoxManage list hdds</command> + для отображения зарегистрированных образов. Можно указывать + как абсолютный, так и относительный пути к носителю. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--autoreset=on | off</option></term> + <listitem><para> + Указывает, сбрасывать ли автоматически неизменяемый + жесткий диск при каждом старте виртуальной машины (ВМ). + Эта опция только для неизменяемых жестких дисков и + значение по умолчанию <literal>on</literal>. + Смотрите <xref linkend="hdimagewrites" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--compact</option></term> + <listitem><para> + Сжимает образы дисков путем удаления блоков содержащих + только нули. Эта опция уменьшает динамически расширяемый + образ и уменьшает <emphasis>физический</emphasis> размер + образа не влияя на логический размер виртуального диска. + </para><para> + Можно использовать эту опцию для базовых образов или + для разностных образов, созданных как часть снимка. + </para><note> + <para> + Перед сжатием образа, необходимо использовать подходящее + ПО для обнуления свободного пространства в гостевой + системе. Например: + </para> + <itemizedlist> + <listitem><para> + <emphasis role="bold">Гости Windows.</emphasis> Запустите + команду <command>sdelete -z</command>. + </para></listitem> + <listitem><para> + <emphasis role="bold">Гости Linux.</emphasis> Используйте + утилиту <command>zerofree</command>, которая поддерживает + файловые системы <literal>ext2</literal> и + <literal>ext3</literal>. + </para></listitem> + <listitem><para> + <emphasis role="bold">Гости Mac OS X.</emphasis> Используйте + команду <command>diskutil secureErase freespace 0 /</command>. + </para></listitem> + </itemizedlist> + </note><para> + Заметим, что эта опция может использоваться только для + сжатия VDI образов. Для сжатия не-VDI образов, можно + обнулить свободные блоки и затем клонировать диск в + любой другой динамически расширяемый формат. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--description=<replaceable>описание</replaceable></option></term> + <listitem><para> + Задает текстовое описание носителя. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--move=<replaceable>путь</replaceable></option></term> + <listitem><para> + Задает относительный или абсолютный путь к носителю в + хост-системе. Используйте эту опцию для перемещения + носителя в другое расположения в хост-системе. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--property=<replaceable>имя</replaceable>=<replaceable>значение</replaceable></option></term> + <listitem><para> + Задает имя и значение свойства носителя. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--resize=<replaceable>размер</replaceable></option></term> + <listitem><para> + Задает новую емкость существующего образа в МБ. Эту опцию + можно использовать только для увеличения емкости образа. + Невозможно уменьшить емкость образа. + </para><para> + Заметим, можно изменить размер только динамически расширяемого + диска, использующих форматы VDI и VHD. Эта опция подстраивает + <emphasis>логический</emphasis> размер виртуального диска и + лишь немного влияет на физический размер. + </para><para> + Например, если ваш динамически расширяемый 10 ГБ диск полон, + можно использовать опцию <option>--resize 15360</option> + для увеличения емкости существующего диска до 15 ГБ + (15360 МБ). Эта операция позволяет избежать создания нового + диска и копирования всех данных со старого внутри ВМ. + </para><para> + Обратите внимание, эта опция меняет емкость диска. Поэтому, + может понадобиться воспользоваться впоследствии программой + управления разделами в гостевой системе для подгонки + разделов под изменившийся размер диска. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--resizebyte=<replaceable>размер</replaceable></option></term> + <listitem><para> + Задает новую емкость существующего образа в байтах. + Эта опция подобна опции <option>--resize</option>, + за исключением того, что размер задается в байтах а + не в МБ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--setlocation=<replaceable>путь</replaceable></option></term> + <listitem><para> + Задает новое расположение носителя в хост-системе после + перемещения. Путь может быть как относительно текущей + директории так и абсолютным. + </para><para> + Заметим, что команда <command>VBoxManage modifymedium</command> + не производит какие-либо проверки указанного пути. Убедитесь, + что путь корректен. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--type</option></term> + <listitem><para> + Задает новый тип режима существующего образа. Допустимые + значения <literal>normal</literal>, + <literal>immutable</literal>, + <literal>writethrough</literal>, + <literal>multi-attach</literal>, + <literal>shareable</literal>, and + <literal>readonly</literal>. Описание этих типов режимов + смотрите в <xref linkend="hdimagewrites" />. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда изменяет описание файла образа диска, называемого + <filename>disk01.vdi</filename>. + </para> +<screen>$ VBoxManage modifymedium disk disk01.vdi --description "Oracle Linux 7 image"</screen> + <para> + Следующая команда изменяет режим записи для файла образа диска, + называемого <filename>disk01.vdi</filename>. + </para> +<screen>$ VBoxManage modifymedium disk disk01.vdi --type writethrough</screen> + </refsect1> + + <refsect1> + <title>Смотрите также</title> + <para> + <xref linkend="vboxmanage-list" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-modifynvram.xml b/doc/manual/ru_RU/man_VBoxManage-modifynvram.xml new file mode 100644 index 00000000..5e0f9571 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-modifynvram.xml @@ -0,0 +1,242 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage modifynvram +--> +<!-- + Copyright (C) 2021-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-modifynvram" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage modifynvram</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-modifynvram</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-modifynvram</refname> + <refpurpose>Отображение и изменение содержимого NVRAM виртуальной машины</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-inituefivarstore"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">inituefivarstore</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-enrollmssignatures"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">enrollmssignatures</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-enrollorclpk"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">enrollorclpk</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-enrollpk"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">enrollpk</arg> + <arg>--platform-key=<replaceable>имя-файла</replaceable></arg> + <arg>--owner-uuid=<replaceable>uuid</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-listvars"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">listvars</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-queryvar"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">queryvar</arg> + <arg>--name=<replaceable>имя</replaceable></arg> + <arg>--filename=<replaceable>имя-файла</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-deletevar"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">deletevar</arg> + <arg>--name=<replaceable>имя</replaceable></arg> + <arg>--owner-uuid=<replaceable>uuid</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-changevar"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="plain">changevar</arg> + <arg>--name=<replaceable>имя</replaceable></arg> + <arg>--filename=<replaceable>имя-файла</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + + <para>Команды "modifynvram" предназначены для экспертов, которые хотят изучить и изменить + хранилище переменных UEFI виртуальной машины. Любые допущенные здесь ошибки могут + привести машину в нерабочее состояние.</para> + + <refsect2 id="vboxmanage-modifynvram-common-options"> + <title>Общие параметры</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>Все подкоманды <command>modifynvram</command> выполняются на работающей виртуальной + машине:</para> + <variablelist> + <varlistentry> + <term><replaceable>uuid|имя-ВМ</replaceable></term> + <listitem><para>Или UUID или имя ВМ (чувствительно к регистру).</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-inituefivarstore"> + <title>modifynvram inituefivarstore</title> + <remark role="help-copy-synopsis"/> + <para> + Инициализирует хранилище переменных UEFI в состояние по умолчанию. Все ранее + существовавшие хранилища переменных удаляются. Используйте с особой осторожностью! + </para> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-enrollmssignatures"> + <title>modifynvram enrollmssignatures</title> + <remark role="help-copy-synopsis"/> + <para> + Регистрирует стандартные подписи Microsoft KEK и DB, необходимые для безопасной загрузки UEFI. + </para> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-enrollorclpk"> + <title>modifynvram enrollorclpk</title> + <remark role="help-copy-synopsis"/> + <para> + Регистрирует ключ платформы по умолчанию, предоставленный Oracle, необходимый для безопасной загрузки UEFI. + </para> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-enrollpk"> + <title>modifynvram enrollpk</title> + <remark role="help-copy-synopsis"/> + <para> + Регистрирует пользовательский ключ платформы переданный пользователем, необходимый + для безопасной загрузки UEFI. Следующие команды используют openssl для генерации + нового ключа платформы: + </para> +<screen>$ openssl req -new -x509 -newkey rsa:2048 -keyout PK.key -out PK.crt</screen> +<screen>$ openssl x509 -in PK.crt -out PK.cer -outform DER</screen> + <variablelist> + <varlistentry> + <term><option>--platform-key=<replaceable>имя-файла</replaceable></option></term> + <listitem><para>Ключ платформы переданный в качестве X.509 подписи, зашифрованной DER.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--owner-uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para>UUID идентифицирующий владельца ключа платформы.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-listvars"> + <title>modifynvram listvars</title> + <remark role="help-copy-synopsis"/> + <para> + Показывает все переменные UEFI в хранилище виртуальной машины относительно UUID их владельца. + </para> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-queryvar"> + <title>modifynvram queryvar</title> + <remark role="help-copy-synopsis"/> + <para> + Запрашивает содержимое данной переменной UEFI по ее имени. + </para> + <variablelist> + <varlistentry> + <term><option>--name=<replaceable>имя</replaceable></option></term> + <listitem><para>имя запрашиваемой переменной UEFI.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--filename=<replaceable>имя-файла</replaceable></option></term> + <listitem> + <para> + Куда сохранять содержимое переменной в случае успеха. Это необязательно. + Если не указан, содержимое будет выдано в терминал как hex дамп. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-deletevar"> + <title>modifynvram deletevar</title> + <remark role="help-copy-synopsis"/> + <para> + Удаляет данную переменную по ее имени и UUID владельца. + </para> + <variablelist> + <varlistentry> + <term><option>--name=<replaceable>имя</replaceable></option></term> + <listitem><para>Имя удаляемой переменной UEFI.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--owner-uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para>UUID владельца удаляемой переменной.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-changevar"> + <title>modifynvram changevar</title> + <remark role="help-copy-synopsis"/> + <para> + Изменяет содержимое переменной UEFI на содержимое указанного файла. + </para> + <variablelist> + <varlistentry> + <term><option>--name=<replaceable>имя</replaceable></option></term> + <listitem><para>Имя изменяемой переменной UEFI.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--filename=<replaceable>имя-файла</replaceable></option></term> + <listitem> + <para>Файл с данными.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-modifyvm.xml b/doc/manual/ru_RU/man_VBoxManage-modifyvm.xml new file mode 100644 index 00000000..b1b0cc07 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-modifyvm.xml @@ -0,0 +1,2740 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage modifyvm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-modifyvm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage modifyvm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-modifyvm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-modifyvm</refname> + <refpurpose>изменение настроек остановленной виртуальной машины</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-general"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg>--name=<replaceable>имя</replaceable></arg> + <arg>--groups= <arg choice="plain"><replaceable>группа</replaceable> [,<replaceable>группа</replaceable>...]</arg></arg> + <arg>--description=<replaceable>описание</replaceable></arg> + <arg>--os-type=<replaceable>тип-ОС</replaceable></arg> + <arg>--icon-file=<replaceable>имя-файла</replaceable></arg> + <arg>--memory=<replaceable>размер-в-МБ</replaceable></arg> + <arg>--page-fusion=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vram=<replaceable>размер-в-МБ</replaceable></arg> + <arg>--acpi=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--ioapic=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--hardware-uuid=<replaceable>UUID</replaceable></arg> + <arg>--cpus=<replaceable>число-ЦПУ</replaceable></arg> + <arg>--cpu-hotplug=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--plug-cpu=<replaceable>CPU-ID</replaceable></arg> + <arg>--unplug-cpu=<replaceable>CPU-ID</replaceable></arg> + <arg>--cpu-execution-cap=<replaceable>число</replaceable></arg> + <arg>--pae=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--long-mode=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--ibpb-on-vm-exit=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--ibpb-on-vm-entry=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--spec-ctrl=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--l1d-flush-on-sched=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--l1d-flush-on-vm-entry=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--mds-clear-on-sched=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--mds-clear-on-vm-entry=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--cpu-profile=<group choice="plain"> + <arg choice="plain">host</arg> + <arg choice="plain">Intel 8086</arg> + <arg choice="plain">Intel 80286</arg> + <arg choice="plain">Intel 80386</arg> + </group></arg> + <arg>--hpet=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--hwvirtex=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--triple-fault-reset=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--apic=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--x2apic=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--paravirt-provider=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">default</arg> + <arg choice="plain">legacy</arg> + <arg choice="plain">minimal</arg> + <arg choice="plain">hyperv</arg> + <arg choice="plain">kvm</arg> + </group></arg> + <arg>--paravirt-debug= <arg choice="plain"><replaceable>ключ</replaceable>=<replaceable>значение</replaceable> [,<replaceable>ключ</replaceable>=<replaceable>значение</replaceable>...]</arg></arg> + <arg>--nested-paging=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--large-pages=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vtx-vpid=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vtx-ux=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nested-hw-virt=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--virt-vmsave-vmload=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--accelerate-3d=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--accelerate-2d-video=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--chipset=<group choice="plain"> + <arg choice="plain">ich9</arg> + <arg choice="plain">piix3</arg> + </group></arg> + <arg>--iommu=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">automatic</arg> + <arg choice="plain">amd</arg> + <arg choice="plain">intel</arg> + </group></arg> + <arg>--tpm-type=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">1.2</arg> + <arg choice="plain">2.0</arg> + <arg choice="plain">host</arg> + <arg choice="plain">swtpm</arg> + </group></arg> + <arg>--tpm-location=<group choice="plain"> + <arg choice="plain"><replaceable>расположение</replaceable></arg> + </group></arg> + <arg>--bios-logo-fade-in=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--bios-logo-fade-out=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--bios-logo-display-time=<replaceable>миллисекунды</replaceable></arg> + <arg>--bios-logo-image-path=<replaceable>путь</replaceable></arg> + <arg>--bios-boot-menu=<group choice="plain"> + <arg choice="plain">disabled</arg> + <arg choice="plain">menuonly</arg> + <arg choice="plain">messageandmenu</arg> + </group></arg> + <arg>--bios-apic=<group choice="plain"> + <arg choice="plain">disabled</arg> + <arg choice="plain">apic</arg> + <arg choice="plain">x2apic</arg> + </group></arg> + <arg>--bios-system-time-offset=<replaceable>миллисекунды</replaceable></arg> + <arg>--bios-pxe-debug=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--system-uuid-le=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--boot<replaceable>X</replaceable>=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">floppy</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">disk</arg> + <arg choice="plain">net</arg> + </group></arg> + <arg>--rtc-use-utc=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--graphicscontroller=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">vboxvga</arg> + <arg choice="plain">vmsvga</arg> + <arg choice="plain">vboxsvga</arg> + </group></arg> + <arg>--snapshot-folder=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain"><replaceable>путь</replaceable></arg> + </group></arg> + <arg>--firmware=<group choice="plain"> + <arg choice="plain">bios</arg> + <arg choice="plain">efi</arg> + <arg choice="plain">efi32</arg> + <arg choice="plain">efi64</arg> + </group></arg> + <arg>--guest-memory-balloon=<replaceable>размер-в-МБ</replaceable></arg> + <arg>--default-frontend=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain"><replaceable>имя</replaceable></arg> + </group></arg> +<!-- There are currently undocumented options --iocache and +--iocachesize which are scheduled for removal. Not worth spending +time on documenting it. --> + <arg>--vm-process-priority=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain">flat</arg> + <arg choice="plain">low</arg> + <arg choice="plain">normal</arg> + <arg choice="plain">high</arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-networking"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg>--nic<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">null</arg> + <arg choice="plain">nat</arg> + <arg choice="plain">bridged</arg> + <arg choice="plain">intnet</arg> + <arg choice="plain">hostonly</arg> + <arg choice="plain">hostonlynet</arg> + <arg choice="plain">generic</arg> + <arg choice="plain">natnetwork</arg> + </group></arg> + <arg>--nic-type<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">Am79C970A</arg> + <arg choice="plain">Am79C973</arg> + <arg choice="plain">82540EM</arg> + <arg choice="plain">82543GC</arg> + <arg choice="plain">82545EM</arg> + <arg choice="plain">virtio</arg> + </group></arg> + <arg>--cable-connected<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nic-trace<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nic-trace-file<replaceable>N</replaceable>=<replaceable>имя-файла</replaceable></arg> + <arg>--nic-property<replaceable>N</replaceable>=<replaceable>имя</replaceable>= <arg><replaceable>значение</replaceable></arg></arg> + <arg>--nic-speed<replaceable>N</replaceable>=<replaceable>кбит-в-сек</replaceable></arg> + <arg>--nic-boot-prio<replaceable>N</replaceable>=<replaceable>приоритет</replaceable></arg> + <arg>--nic-promisc<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">deny</arg> + <arg choice="plain">allow-vms</arg> + <arg choice="plain">allow-all</arg> + </group></arg> + <arg>--nic-bandwidth-group<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain"><replaceable>name</replaceable></arg> + </group></arg> + <arg>--bridge-adapter<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain"><replaceable>device-name</replaceable></arg> + </group></arg> + <arg>--host-only-adapter<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain"><replaceable>device-name</replaceable></arg> + </group></arg> + <arg>--host-only-net<replaceable>N</replaceable>=<replaceable>имя-сети</replaceable></arg> + <arg>--intnet<replaceable>N</replaceable>=<replaceable>имя-сети</replaceable></arg> + <arg>--nat-network<replaceable>N</replaceable>=<replaceable>имя-сети</replaceable></arg> + <arg>--nic-generic-drv<replaceable>N</replaceable>=<replaceable>имя-драйвера</replaceable></arg> + <arg>--mac-address<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">auto</arg> + <arg choice="plain"><replaceable>MAC-адрес</replaceable></arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-networking-nat"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg>--nat-net<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain"><replaceable>сеть</replaceable></arg> + <arg choice="plain">default</arg> + </group></arg> + <arg>--nat-pf<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">[<replaceable>имя-правила</replaceable>],tcp</arg> + <arg choice="plain">udp,[<replaceable>IP-хоста</replaceable>],<replaceable>порт-хоста</replaceable>,[<replaceable>IP-гостя</replaceable>],<replaceable>порт-гостя</replaceable></arg> + </group></arg> + <arg>--nat-pf<replaceable>N</replaceable>=delete=<replaceable>имя-правила</replaceable></arg> + <arg>--nat-tftp-prefix<replaceable>N</replaceable>=<replaceable>префикс</replaceable></arg> + <arg>--nat-tftp-file<replaceable>N</replaceable>=<replaceable>имя-файла</replaceable></arg> + <arg>--nat-tftp-server<replaceable>N</replaceable>=<replaceable>IP-адрес</replaceable></arg> + <arg>--nat-bind-ip<replaceable>N</replaceable>=<replaceable>IP-адрес</replaceable></arg> + <arg>--nat-dns-pass-domain<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nat-dns-proxy<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nat-dns-host-resolver<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nat-localhostreachable<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nat-settings<replaceable>N</replaceable>=[<replaceable>mtu</replaceable>],[<replaceable>отправка-сокет</replaceable>],[<replaceable>прием-сокет</replaceable>],[<replaceable>отправка-tcp</replaceable>],[<replaceable>прием-tcp</replaceable>]</arg> + <arg>--nat-alias-mode<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain">[log],[proxyonly],[sameports]</arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-other-hardware"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg>--mouse=<group choice="plain"> + <arg choice="plain">ps2</arg> + <arg choice="plain">usb</arg> + <arg choice="plain">usbtablet</arg> + <arg choice="plain">usbmultitouch</arg> + </group></arg> + <arg>--keyboard=<group choice="plain"> + <arg choice="plain">ps2</arg> + <arg choice="plain">usb</arg> + </group></arg> + <arg>--uart<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">off</arg> + <arg choice="plain"><replaceable>IO-база</replaceable> <replaceable>IRQ</replaceable></arg> + </group></arg> + <arg>--uart-mode<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">disconnected</arg> + <arg choice="plain">server <replaceable>канал</replaceable></arg> + <arg choice="plain">client <replaceable>канал</replaceable></arg> + <arg choice="plain">tcpserver <replaceable>порт</replaceable></arg> + <arg choice="plain">tcpclient <replaceable>имя-хоста</replaceable>:<replaceable>порт</replaceable></arg> + <arg choice="plain">file <replaceable>имя-файла</replaceable></arg> + <arg choice="plain"><replaceable>имя-устройства</replaceable></arg> + </group></arg> + <arg>--uart-type<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">16450</arg> + <arg choice="plain">16550A</arg> + <arg choice="plain">16750</arg> + </group></arg> + <arg>--lpt-mode<replaceable>N</replaceable>=<replaceable>имя-устройства</replaceable></arg> + <arg>--lpt<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">off</arg> + <arg choice="plain"><replaceable>IO-база</replaceable> <replaceable>IRQ</replaceable></arg> + </group></arg> + <arg>--audio-controller=<group choice="plain"> + <arg choice="plain">ac97</arg> + <arg choice="plain">hda</arg> + <arg choice="plain">sb16</arg> + </group></arg> + <arg>--audio-codec=<group choice="plain"> + <arg choice="plain">stac9700</arg> + <arg choice="plain">ad1980</arg> + <arg choice="plain">stac9221</arg> + <arg choice="plain">sb16</arg> + </group></arg> + <arg>--audio-driver=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">default</arg> + <arg choice="plain">null</arg> + <arg choice="plain">dsound</arg> + <arg choice="plain">was</arg> + <arg choice="plain">oss</arg> + <arg choice="plain">alsa</arg> + <arg choice="plain">pulse</arg> + <arg choice="plain">coreaudio</arg> + </group></arg> + <arg>--audio-enabled=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--audio-in=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--audio-out=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--clipboard-mode=<group choice="plain"> + <arg choice="plain">disabled</arg> + <arg choice="plain">hosttoguest</arg> + <arg choice="plain">guesttohost</arg> + <arg choice="plain">bidirectional</arg> + </group></arg> +<!-- There is a currently undocumented option --clipboard-file-transfers. +The implementation is not finished, so postpone documenting until it +actually is ready for users. --> + <arg>--drag-and-drop=<group choice="plain"> + <arg choice="plain">disabled</arg> + <arg choice="plain">hosttoguest</arg> + <arg choice="plain">guesttohost</arg> + <arg choice="plain">bidirectional</arg> + </group></arg> + <arg>--monitor-count=<replaceable>количество</replaceable></arg> + <arg>--usb-ehci=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--usb-ohci=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--usb-xhci=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--usb-rename=<replaceable>старое-имя</replaceable> <replaceable>новое-имя</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-recording"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg>--recording=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--recording-screens=<group choice="plain"> + <arg choice="plain">all</arg> + <arg choice="plain"><replaceable>ID-экрана</replaceable> [<replaceable>ID-экрана</replaceable>...]</arg> + </group></arg> + <arg>--recording-file=<replaceable>имя-файла</replaceable></arg> + <arg>--recording-max-size=<replaceable>МБ</replaceable></arg> + <arg>--recording-max-time=<replaceable>миллисекунды</replaceable></arg> + <arg>--recording-opts= <arg choice="plain"><replaceable>ключ</replaceable>=<replaceable>значение</replaceable> [,<replaceable>ключ</replaceable>=<replaceable>значение</replaceable>...]</arg></arg> + <arg>--recording-video-fps=<replaceable>кадров-в-сек</replaceable></arg> + <arg>--recording-video-rate=<replaceable>rate</replaceable></arg> + <arg>--recording-video-res=<replaceable>ширина</replaceable> <replaceable>высота</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-vrde"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg>--vrde=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vrde-property=<replaceable>имя-свойства</replaceable>= <arg><replaceable>значение-свойства</replaceable></arg></arg> + <arg>--vrde-extpack=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain"><replaceable>имя</replaceable></arg> + </group></arg> + <arg>--vrde-port=<replaceable>порт</replaceable></arg> + <arg>--vrde-address=<replaceable>IP-хоста</replaceable></arg> + <arg>--vrde-auth-type=<group choice="plain"> + <arg choice="plain">null</arg> + <arg choice="plain">external</arg> + <arg choice="plain">guest</arg> + </group></arg> + <arg>--vrde-auth-library=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain"><replaceable>имя</replaceable></arg> + </group></arg> + <arg>--vrde-multi-con=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vrde-reuse-con=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vrde-video-channel=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vrde-video-channel-quality=<replaceable>процент</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-teleport"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg>--teleporter=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--teleporter-port=<replaceable>порт</replaceable></arg> + <arg>--teleporter-address=<group choice="plain"> + <arg choice="plain"><replaceable>адрес</replaceable></arg> + <arg choice="plain">empty</arg> + </group></arg> + <arg>--teleporter-password=<replaceable>пароль</replaceable></arg> + <arg>--teleporter-password-file=<group choice="plain"> + <arg choice="plain"><replaceable>имя-файла</replaceable></arg> + <arg choice="plain">stdin</arg> + </group></arg> + <arg>--cpuid-portability-level=<replaceable>уровень</replaceable></arg> + <arg>--cpuid-set=<replaceable>лист</replaceable><arg>:<replaceable>подлист</replaceable></arg> <replaceable>eax</replaceable> <replaceable>ebx</replaceable> <replaceable>ecx</replaceable> <replaceable>edx</replaceable></arg> + <arg>--cpuid-remove=<replaceable>лист</replaceable><arg>:<replaceable>подлист</replaceable></arg></arg> + <arg>--cpuid-remove-all</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-debugging"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg>--tracing-enabled=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--tracing-config=<replaceable>строка</replaceable></arg> + <arg>--tracing-allow-vm-access=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-usbcardreader"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg>--usb-card-reader=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-autostart"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg>--autostart-enabled=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--autostart-delay=<replaceable>секунды</replaceable></arg> +<!-- There is a currently undocumented option --autostop-type. +Most autostart service implementations either ignore it or rely it is +left unchanged due to otherwise running into timeouts established by the +host OS, defeating the purpose. Not worth spending time on documenting +it unless this changes. --> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-pcipassthrough"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg>--pci-attach=<replaceable>PCI-адрес-хоста</replaceable><arg>@<replaceable>гостевой-PCI-адрес-шины</replaceable></arg></arg> + <arg>--pci-detach=<replaceable>PCI-адрес-хоста</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-testing"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg>--testing-enabled=<group choice="plain"><arg choice="plain">on</arg><arg choice="plain">off</arg></group></arg> + <arg>--testing-mmio=<group choice="plain"><arg choice="plain">on</arg><arg choice="plain">off</arg></group></arg> + <arg>--testing-cfg-dword<replaceable>idx</replaceable>=<replaceable>значение</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage modifyvm</command> позволяет изменить + свойства зарегистрированной неработающей на текущий момент + виртуальной машины (ВМ). + </para> + <para> + Большинство этих свойств соответствуют настройкам ВМ отображаемых + в диалоге <emphasis role="bold">Настройки</emphasis> Менеджера + VirtualBox для каждой ВМ. Смотрите <xref linkend="BasicConcepts" />. + Однако, некоторые настройки могут отображаться или управляться + только командой <command>VBoxManage</command>. + </para> + <para> + Можно использовать команду <command>VBoxManage modifyvm</command> + для изменения настроек только если ВМ выключена. ВМ не может быть + в работающем или сохраненном состоянии при использовании этой + команды. + </para> + <para> + Можно использовать команду <command>VBoxManage controlvm</command> + для изменения некоторых настроек ВМ динамически, пока ВМ работает. + Смотрите <xref linkend="vboxmanage-controlvm" />. + </para> + <refsect2 id="vboxmanage-modifyvm-general"> + <title>Общие настройки</title> + <remark role="help-copy-synopsis"/> + <para> + Следующие опции позволяют вам изменить общую информаицю о вашей ВМ. + </para> + <para> + Команда <command>VBoxManage modifyvm</command> поддерживает следующие + опции: + </para> + <variablelist> + <varlistentry> + <term><option>--name=<replaceable>имя-ВМ</replaceable></option></term> + <listitem><para> + Изменяет имя ВМ и связанных с ней внутренних файлов. Смотрите + <xref linkend="vboxmanage-createvm"/>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--groups=<replaceable>группа</replaceable></option></term> + <listitem><para> + Изменяет членство в группе для ВМ. Имена групп всегда + начинаются с символа слэш (<literal>/</literal>) и могут + быть вложены. По умолчанию, ВМ - члены группы + <literal>/</literal>. ВМ может входить в несколько групп, + но ее первичная группа определяет структуру директорий, + где внутренние файлы ВМ располагаются по умолчанию. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--description=<replaceable>описание</replaceable></option></term> + <listitem><para> + Изменяет необязательное описание ВМ. Используйте описание + для записи подробностей о ВМ в осмысленном виде. Графический + интерфейс понимает HTML разметку, тогда как команда + <command>VBoxManage modifyvm</command> позволяет включать + произвольный текст, который может содержать несколько строк. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--os-type=<replaceable>тип-ОС</replaceable></option></term> + <listitem><para> + Задает информацию о гостевой операционной системе (ОС) в ВМ. + Используйте команду <command>VBoxManage list ostypes</command> + для отображения идентификаторов типов ОС. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--icon-file=<replaceable>имя-файла</replaceable></option></term> + <listitem><para> + Задает путь к файлу иконки ВМ в формате PNG в + хост-системе. Иконка отображается в интерфейсе Менеджера + ВМ и когда ВМ запущена в режиме графического интерфейса. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--memory=<replaceable>размер</replaceable></option></term> + <listitem><para> + Задает количество оперативной памяти хоста, выделенной ВМ. + Размер в МБ. Смотрите <xref linkend="create-vm-wizard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--page-fusion=on | off</option></term> + <listitem><para> + Включает или отключает функцию Page Fusion, которая + по умолчанию отключена. Используйте функцию Page + Fusion для минимизации дублирования памяти между ВМ, + имеющих подобную конфигурацию и работающих на той же + хост-системе. Смотрите <xref linkend="guestadd-pagefusion" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vram=<replaceable>размер</replaceable></option></term> + <listitem><para> + Задает количество оперативной памяти, выделенной + графической карте. Смотрите <xref linkend="settings-display" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--acpi=on | off</option></term> + <listitem><para> + Определяет поддерживает ли ВМ ACPI. Смотрите + <xref linkend="settings-motherboard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ioapic=on | off</option></term> + <listitem><para> + Определяет поддерживает ли ВМ I/O APIC. Смотрите + <xref linkend="settings-motherboard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--hardware-uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Задает Универсальный Уникальный Идентификатор (UUID) + для представления гостевой ВМ в таблицах памяти + (DMI/SMBIOS), в оборудовании и свойствах ВМ. По умолчанию + этот UUID оборудования такой же как UUID ВМ. Клонирование + и функция портирования автоматически сохраняет значение + UUID оборудования. Аналогично для экспорта и импорта + виртуальной конфигурации, но только если обе операции + выполняются &product-name;. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpus=<replaceable>число-ЦПУ</replaceable></option></term> + <listitem><para> + Задает количество виртуальных ЦПУ, назначенных ВМ. + Смотрите <xref linkend="settings-processor" />. + </para><para> + Если горячее подключение ЦПУ включено, эта опция задает + максимальное количество виртуальных ЦПУ, которые можно + подключить к ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpu-hotplug=on | off</option></term> + <listitem><para> + Включает или выключает горячее подключение ЦПУ. Когда + включено, можно динамически добавлять и удалять виртуальные + ЦПУ в ВМ. Смотрите <xref linkend="cpuhotplug" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--plug-cpu=<replaceable>CPU-ID</replaceable></option></term> + <listitem><para> + Добавляет виртуальный ЦПУ в ВМ. + <replaceable>CPU-ID</replaceable> - это индекс добавляемого + вируального ЦПУ. Допустимое значение индекса - это число + от <literal>0</literal> до максимального количества ЦПУ, + заданных опцией <option>--cpus</option>. + </para><para> + Используйте эту опцию только когда включено горячее подключение ЦПУ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unplug-cpu=<replaceable>CPU-ID</replaceable></option></term> + <listitem><para> + Удалить виртуальный ЦПУ из ВМ. + <replaceable>CPU-ID</replaceable> - это индекс удаляемого + вируального ЦПУ. Допустимое значение индекса - это число + от <literal>1</literal> до максимального количества ЦПУ, + заданных опцией <option>--cpus</option>. + </para><para> + Используйте эту опцию только когда включено горячее подключение ЦПУ. + </para><para> + Обратите внимание, что нельзя удалить ЦПУ 0. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpuexectioncap=<replaceable>процент</replaceable></option></term> + <listitem><para> + Указывает, сколько времени ЦПУ может использовать + виртуальный ЦПУ. Допустимые значения от <literal>1</literal> + до <literal>100</literal>. Значение 50 показывает, что + единичные виртуальный ЦПУ может использовать до 50% + единичного ЦПУ хоста. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--pae=on | off</option></term> + <listitem><para> + Включает или выключает расширение физических адресов (PAE). + Смотрите <xref linkend="settings-processor" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--long-mode=on | off</option></term> + <listitem><para> + Включает или выключает длинный режим. Смотрите + <xref linkend="settings-processor" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ibpb-on-vm-exit=on | off</option></term> + <listitem><para> + Включает использование барьера предсказателя неявных + ветвлений (IBPB) при каждом выходе из ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ibpb-on-vm-entry=on | off</option></term> + <listitem><para> + Включает использование барьера предсказателя неявных + ветвлений (IBPB) при каждом входе в ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--spec-ctrl=on | off</option></term> + <listitem><para> + Включает или выключает отображение интерфейсов управления + спекуляцией для гостевой ВМ. Эти интерфейсы должны + быть доступны в хост-системе. + </para><para> + В зависимости от ЦПУ хоста и нагрузки, включение + управления спекуляцией может значительно уменьшить + производительность. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--l1d-flush-on-sched=on | off</option></term> + <listitem><para> + Включает или отключает сброс кэша данных L1, когда + поток запланирован на исполнение гостевого кода. Смотрите + <xref linkend="sec-rec-cve-2018-3646" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--l1d-flush-on-vm-entry=on | off</option></term> + <listitem><para> + Включает или отключает сброс кэша данных L1 при каждом + входе в ВМ. Смотрите <xref linkend="sec-rec-cve-2018-3646" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mds-clear-on-sched=on | off</option></term> + <listitem><para> + Включает очистку буфера ЦПУ когда поток запланирован + на выполнение гостевого кода. Смотрите + <xref linkend="sec-rec-cve-2018-12126-et-al" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mds-clear-on-vm-entry=on | off</option></term> + <listitem><para> + Включает очистку буфера ЦПУ при каждом входе в ВМ. + Смотрите <xref linkend="sec-rec-cve-2018-12126-et-al" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpu-profile=host | Intel 8086 | Intel 80286 | Intel 80386</option></term> + <listitem><para> + Задает профиль, используемый для эмуляции гостевого + ЦПУ. Задайте значение, основанное на ЦПУ хост-системы + (<literal>host</literal>) или одной из следующих более + старых микроархитектурах Intel: <literal>8086</literal>, + <literal>80286</literal> или <literal>80386</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--hpet=on | off</option></term> + <listitem><para> + Включает или выключает Таймер Событий Высокого + Разрешения (HPET), заменяющий устаревший системный + тайммер. Эта функция отключена по умолчанию. Заметим, + что HPET поддерживается в Windows начиная с Vista. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--hwvirtex=on | off</option></term> + <listitem><para> + Включает или отключает использования расширение + виртуализации оборудования в процессоре хост-системы. + Такими расширениями являются Intel VT-x или AMD-V. + Смотрите <xref linkend="hwvirt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--triple-fault-reset=on | off</option></term> + <listitem><para> + Включает или отключает сброс гостевой ВМ вместо включения + медитации гуру. Некоторые гостевые ВМ вызывают тройной + сбой для сброса ЦПУ, поэтому иногда сброс гостевой ВМ - + это наилучший исход. Эта опция применяется только к + гостевым системам не использующих симметричную + многопроцессорность (SMP). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--apic=on | off</option></term> + <listitem><para> + Включает или выключает APIC. С APIC, ОС может + использовать более 16 запросов на прерывание (IRQ) + избегая совместное использование IRQ для улучшения + надежности. APIC включен по умолчанию. Смотрите + <xref linkend="settings-motherboard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--x2apic=on | off</option></term> + <listitem><para> + Включает или выключает функцию ЦПУ x2APIC. ЦПУ x2APIC + позволяет ОС работать более эффективно в конфигурациях + с большим количеством ядер и оптимизировать распределение + прерываний в виртуализированном окружении. Эта функция + включена по умолчанию. + </para><para> + Отключите эту функцию если ОС, работающая в хост-системе, + или гостевая ВМ не совместимы с ЦПУ x2APIC. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--paravirt-provider=none | default | legacy | minimal | hyperv | kvm</option></term> + <listitem><para> + Указывает один из следующих интерфейсов + паравиртуализации предоставленный гостевой ОС: + </para><itemizedlist> + <listitem><para> + <literal>none</literal> не предоставляет каких-либо + интерфейсов паравиртуализации. + </para></listitem> + <listitem><para> + <literal>default</literal> выбирает подходящий + интерфейс, основанный на типе гостевой ОС при старте + ВМ. Это значение по умолчанию при создании новой ВМ. + </para></listitem> + <listitem><para> + <literal>legacy</literal> выбирает интерфейс + паравиртуализации для ВМ, созданный более старыми + версиями &product-name;. + </para></listitem> + <listitem><para> + <literal>minimal</literal> требуется для гостевых ВМ + с Mac OS X. + </para></listitem> + <listitem><para> + <literal>kvm</literal> рекомендуется для гостевых ВМ + Linux. Смотрите <xref linkend="gimproviders" />. + </para></listitem> + <listitem><para> + <literal>hyperv</literal> рекомендуется для гостевых + ВМ Windows. Смотрите <xref linkend="gimproviders" />. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--paravirt-debug=<replaceable>свойство</replaceable>=<replaceable>значение</replaceable></option></term> + <listitem><para> + Задает отладочные свойства, специфичные для провайдера + паравиртуализации, настроенного для указанной ВМ. + Смотрите <xref linkend="gimdebug" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nested-paging=on | off</option></term> + <listitem><para> + Включает или отключает функцию вложенных страниц в + процессоре хост-системы. Эта опция доступна только + если аппаратная виртуализация включена. Смотрите + <xref linkend="hwvirt" /> и + <xref linkend="sec-rec-cve-2018-3646" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--large-pages=on | off</option></term> + <listitem><para> + Включает или отключает использование гипервизором + больших страниц, что может увеличить производительность + до 5%. Использование больших страниц уменьшает + использование TLB и накладные расходы. Эта опция + доступна только если включены и аппаратная виртуализация + и вложенные страницы. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vtx-vpid=on | off</option></term> + <listitem><para> + Включает или отключает использование функцию TLB c метками + (VPID) в процессоре вашей хост-системы. Смотрите + <xref linkend="hwvirt" />. Эта опция доступна только + если аппаратная виртуализация включена на Intel VT-x. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vtx-ux=on | off</option></term> + <listitem><para> + Включает или отключает использование неограниченного + гостевого режима для выполнения гостевой ВМ. Эта опция + доступна только когда аппаратная виртуализация включена + на Intel VT-x. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nested-hw-virt=on | off</option></term> + <listitem><para> + Включает или отключает вложенну виртуализацию. Включение + делает доступной функцию аппаратной виртуализации в ВМ. + Смотрите <xref linkend="nested-virt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--virt-vmsave-vmload=on | off</option></term> + <listitem><para> + Если аппаратная виртуализация включена у хоста с ЦПУ AMD, + эта настройка включает или отключает использование функцию + виртуализированных vmsave/vmload во время исполнения ВМ. + Включена по умолчанию. Рекомендуется оставить включенной, + так как она имеет серьезное влияние на производительность + при выполнении вложенных ВМ при использовании вложенной + аппаратной виртуализации. + <xref linkend="nested-virt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--accelerated3d=on | off</option></term> + <listitem><para> + Включает или выключает аппаратное 3D ускорение для + графических адаптеров, поддерживающих это. Эта опция + работает только при установленных Дополнений Гостевой ОС. + Смотрите <xref linkend="guestadd-3d" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--accelerated2dvideo=on | off</option></term> + <listitem><para> + Включает или отключает 2D видео ускорение для графических + адаптеров, поддерживающих это. Эта опция работает только + при установленных Дополнений Гостевой ОС. Смотрите + <xref linkend="guestadd-2d" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--chipset=piix3 | ich9</option></term> + <listitem><para> + Задать чипсет Intel для эмуляции в &product-name;. + Значение по умолчанию - это чипсет Intel PIIX3 + (<literal>piix3</literal>). + </para><para> + Изменяйте это значение только если нужно ослабить + некоторые ограничения чипсета. Смотрите + <xref linkend="settings-motherboard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--iommu=none | automatic | amd | intel</option></term> + <listitem><para> + Указывает типа IOMMU для эмуляции в &product-name;. + И Intel и AMD IOMMU требуют в настоящее время использование + чипсета Intel ICH9 (Смотрите опцию <option>--chipset</option>). + </para><para> + Допустимые значения: + </para><itemizedlist> + <listitem><para> + <literal>none</literal> – IOMMU отсутствует и это + значение по умолчанию. + </para></listitem> + <listitem><para> + <literal>automatic</literal> – IOMMU присутствует, + но его тип выбирается автоматически, соответствуя + поставщику ЦПУ хоста при включении ВМ. + </para></listitem> + <listitem><para> + <literal>amd</literal> – AMD IOMMU присутствует. + </para></listitem> + <listitem><para> + <literal>intel</literal> – Intel IOMMU присутствует. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--tpm-type=none | 1.2 | 2.0 | host | swtpm</option></term> + <listitem><para> + Указывает тип TPM для эмуляции в &product-name;. + </para><para> + Допустимы следующие значения: + </para><itemizedlist> + <listitem><para> + <literal>none</literal> – TPM отсутствует и это значение по умолчанию. + </para></listitem> + <listitem><para> + <literal>1.2</literal> – TPM, соответствующий спецификации TCG 1.2, присутствует. + </para></listitem> + <listitem><para> + <literal>2.0</literal> – TPM, соответствующий спецификации TCG 2.0, присутствует. + </para></listitem> + <listitem><para> + <literal>host</literal> – TPM хост системы перенаправляется в гостевую систему. + Может быть доступен не на всех поддерживаемых хост платформах. + </para></listitem> + <listitem><para> + <literal>swtpm</literal> – ВМ подключается к эмуляции внешнего TPM, совместимого + с swtpm. Необходиму задать расположение TPM location для подключения (смотрите опцию + <option>--tpm-location</option>). + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-logo-fade-in=on | off</option></term> + <listitem><para> + Указывает, появляется ли логотип BIOS при старте ВМ. По умолчанию + показывается логотип &product-name;. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-logo-fade-out=on | off</option></term> + <listitem><para> + Указывает, исчезает ли логотип BIOS при старте ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-logo-display-time=<replaceable>msec</replaceable></option></term> + <listitem><para> + Задает время отображения логотипа BIOS в миллисекундах. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-logo-image-path=<replaceable>pathname</replaceable></option></term> + <listitem><para> + Заменяет существующий логотип BIOS другим изображением. + Заменяющее изображение должно быть несжатым 16-, 256- или + 16М-цветным файлом bitmap (BMP), не содержащим информацию о + цветовом пространстве (формат Windows 3.0). Также убедитесь + что изображение не больше 640x480 пикселов. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-boot-menu=disabled | menuonly | messageandmenu</option></term> + <listitem><para> + Указывает, позволяет ли BIOS выбрать временное + загрузочное устройство. Допустимые значения: + </para><itemizedlist> + <listitem><para> + <literal>disabled</literal> выводит сообщение об + альтернативном загрузочном устройстве и позволяет + выбрать временное загрузочное устройство нажатием F12. + </para></listitem> + <listitem><para> + <literal>menuonly</literal> подавляет вывод сообщения + об альтернативном загрузочном устройстве, но позволяет + выбрать временное загрузочное устройство нажатием F12. + </para></listitem> + <listitem><para> + <literal>messageandmenu</literal> подавляет сообщение + об альтернативном загрузочном устройстве и предотвращает + выбор временного загрузочного устройства нажатием F12. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-apic=x2apic | apic | disabled</option></term> + <listitem><para> + Задает уровень APIC для прошивки. Допустимые значения: + <literal>x2apic</literal>, <literal>apic</literal> + и <literal>disabled</literal>. Когда значение + <literal>disabled</literal>, ни версия <literal>apic</literal> + ни версия <literal>x2apic</literal> не используются. + </para><para> + Заметим, что если указать значение <literal>x2apic</literal> + и x2APIC не поддерживается виртуальным ЦПУ, уровень + APIC снижается до <literal>apic</literal>, если он + поддерживается. Иначе, уровень APIC снижается до + <literal>disabled</literal>. Аналогично, если указать + значение <literal>apic</literal> и APIC не поддерживается + виртуальным ЦПУ, уровень APIC снижается до + <literal>disabled</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-system-time-offset=<replaceable>миллисекунды</replaceable></option></term> + <listitem><para> + Задает смещение времени в миллисекундах для гостевой ВМ + по отношению ко времени в хост-системе. Если значение + положительное, время в гостевой ВМ опережает время + хост-системы. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-pxe-debug=on | off</option></term> + <listitem><para> + Включает или отключает дополнительный отладочный вывод при + использовании загрузочного ROM Intel PXE. Отладочный вывод + записывается в файл журнала в режиме выпуска. Смотрите + <xref linkend="collect-debug-info" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--system-uuid-le=on | off</option></term> + <listitem><para> + Включает или выключает представление системного UUID в + форме little endian. + Значение по умолчанию <literal>on</literal> для новых ВМ. + Для старых ВМ значение <literal>off</literal> чтобы сохранить + содержиммое таблицы DMI/SMBIOS неизменным, что может быть + важно для активации лицензии Windows. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--boot<replaceable>N</replaceable>=none | floppy | dvd | disk | net</option></term> + <listitem><para> + Позволяет указать порядок загрузочных устройств для ВМ + через назначение одного из типов устройств на каждый из + четырех слотов загрузочных устройств, представленных + <replaceable>N</replaceable> в имени опции. + </para><para> + Значение 1 для в <replaceable>N</replaceable> представляет + первое загрузочное устройство, и так далее. + </para><para> + Типы устройств - это <literal>floppy</literal> для флоппи + дисков, <literal>dvd</literal> для DVD или CD, + <literal>disk</literal> для жестких дисков и + <literal>net</literal> для сетевых устройств. Значение + <literal>none</literal> показывает, что загрузочное устройство + на указанный слот не назначено. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--rtc-use-utc=on | off</option></term> + <listitem><para> + Указывает, что часы реального времени (RTC) используют + скоординированное универсальное время (UTC). Смотрите + <xref linkend="settings-motherboard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--graphicscontroller=none | vboxvga | vmsvga | vboxsvga</option></term> + <listitem><para> + Задает используемый тип графического контроллера. + Смотрите <xref linkend="settings-screen" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--snapshot-folder=default | <replaceable>путь</replaceable></option></term> + <listitem><para> + Указывает имя папки для хранения снимков ВМ. + <literal>default</literal> означает + <filename>Snapshots/</filename> в папке машины. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--firmware=bios | efi | efi32 | efi64</option></term> + <listitem><para> + Указывает прошивку, используемую для загрузки ВМ. Допустимые + значения: <literal>bios</literal>, <literal>efi</literal>, + <literal>efi32</literal> или <literal>efi64</literal>. + Используйте значения EFI с осторожностью. + </para><para> + По умолчанию используется прошивка BIOS. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--guest-memory-balloon=<replaceable>размер</replaceable></option></term> + <listitem><para> + Задает размер гостевого memory balloon. Гостевой memory + balloon - это память выделенная Дополнениями Гостевой ОС + из гостевой ОС и возвращенная гипервизору для использования + другими ВМ. Указывайте <replaceable>размер</replaceable> + в мегабайтах. Значение по умолчанию <literal>0</literal> + мегабайт. Смотрите <xref linkend="guestadd-balloon" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--default-frontend=default | <replaceable>имя</replaceable></option></term> + <listitem><para> + Указывает фронтенд по умолчанию, используемый при + старте указанной ВМ. Если указать <literal>default</literal>, + ВМ запускается в окне рабочего стола пользователя. + Смотрите <xref linkend="vboxmanage-startvm" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vm-process-priority=default | flat | low | normal | high</option></term> + <listitem><para> + Задает схему приоритета, используемую при старте + и работе указанной ВМ. + </para><para> + Допустимы следующие значения: + </para><itemizedlist> + <listitem><para> + <literal>default</literal> – Приоритет процесса + по умолчанию, опрелеляемый ОС. + </para></listitem> + <listitem><para> + <literal>flat</literal> – предполагает политику + планирования, которая устанавливает для процесса + приоритет по умолчанию, при этом, всем потокам процесса + устанавливается один и тот же приоритет. + </para></listitem> + <listitem><para> + <literal>low</literal> – Предполагает политику + планирования, которая устанавливает приоритет процесса + в основном ниже приоритета по умолчанию ОС хоста. + </para></listitem> + <listitem><para> + <literal>normal</literal> – Предполагает политику + планирования, которая честно разделяет ресурсы ЦПУ с + другими процессами, имеющими приоритет по умолчанию + ОС хоста. + </para></listitem> + <listitem><para> + <literal>high</literal> – Предполагает политику + планирования, которая устанавливает приоритет процесса + выше приоритета по умолчанию ОС хоста. Эта политика + может повлиять на другие процессы, заставляя их ожидать + ресурса ЦПУ больше положенного времени, что может + привести к непредсказуемому поведению. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-networking"> + <title>Сетевые настройки</title> + <remark role="help-copy-synopsis"/> + <para> + Следующие опции позволяют изменять сеть в вашей ВМ. Во всех + этих опциях, <replaceable>N</replaceable> - это число больше + нуля, представляющее определенный виртуальный сетевой адаптер, + настраиваемый в данный момент. + </para> + <variablelist> + <varlistentry> + <term><option>--nic<replaceable>N</replaceable>=none | null | nat | natnetwork | bridged | intnet | hostonly | generic</option></term> + <listitem><para> + Настраивает тип сети используемый каждой виртуальной + сетевой картов в ВМ. + </para><para> + Следующие допустимые значения соответствуют режимам, + описанных в<xref linkend="networkingmodes" />: + </para><itemizedlist> + <listitem><para> + <literal>none</literal> – Сеть отсутствует + </para></listitem> + <listitem><para> + <literal>null</literal> – Не подключен к хост-системе + </para></listitem> + <listitem><para> + <literal>nat</literal> – Используется преобразование адресов (NAT) + </para></listitem> + <listitem><para> + <literal>natnetwork</literal> – Используется сеть NAT + </para></listitem> + <listitem><para> + <literal>bridged</literal> – Используется сетевой мост + </para></listitem> + <listitem><para> + <literal>intnet</literal> – Используется внутренняя сеть + </para></listitem> + <listitem><para> + <literal>hostonly</literal> – Используется сеть хоста + </para></listitem> + <listitem><para> + <literal>generic</literal> – Доступ к редко используемым подрежимам + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-type<replaceable>N</replaceable>=Am79C970A | Am79C973 | 82540EM | 82543GC | 82545EM | virtio</option></term> + <listitem><para> + Идентифицирует тип сетевого оборудования, которое + &product-name; представляет гостевой ВМ для указанной + виртуальной сетевой карты. Смотрите + <xref linkend="nichardware" />. + </para><para> + Допустимы следующие значения: + </para><itemizedlist> + <listitem><para> + <literal>Am79C970A</literal> представляет AMD PCNet + PCI II. + </para></listitem> + <listitem><para> + <literal>Am79C973</literal> представляет AMD PCNet + FAST III, что является значением по умолчанию. + </para></listitem> + <listitem><para> + <literal>82540EM</literal> представляет Intel + PRO/1000 MT Desktop. + </para></listitem> + <listitem><para> + <literal>82543GC</literal> представляет Intel + PRO/1000 T Server. + </para></listitem> + <listitem><para> + <literal>82545EM</literal> представляет Intel + PRO/1000 MT Server. + </para></listitem> + <listitem><para> + <literal>virtio</literal> представляет паравиртуализированный + сетевой адаптер. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--cable-connected<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + Временно отсоединяет виртуальный сетевой интерфейс, как + будто вы вытащили сетевой кабель из физического сетевого + интерфейса. Можно использовать эту опцию для сброса + определенных программных компонентов в ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-trace<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + Включает или выключает трассировку сети для указанной + сетевой карты. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-trace-file<replaceable>N</replaceable>=<replaceable>имя-файла</replaceable></option></term> + <listitem><para> + Задает абсолютный путь к файлу, куда записывать информаицю + журнала трассировки. Используйте эту опцию если включена + трассировка сети. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-property<replaceable>N</replaceable>=<replaceable>имя</replaceable>=<replaceable>значение</replaceable></option></term> + <listitem><para> + Позволяет задать значения свойств и передать их редко + используемым сетевым бэкендам. Для использования этой + опции, необходимо также использовать опцию + <option>--nic-generic-drv</option>. + </para><para> + Свойства относятся к движку бэкенда и отличаются между + UDP туннелем и драйверами бэкенда VDE. В качестве + примера смотрите + <xref linkend="network_udp_tunnel" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-speed<replaceable>N</replaceable>=<replaceable>кбит-в-сек</replaceable></option></term> + <listitem><para> + Указывает пропускную способность в килобит в секунду для + редко используемых сетевых подрежимов, таких как сеть + VDE и UDP туннель. Используйте эту опцию, только если + использована опция <option>--nic</option> для включения + generic сети для указанной виртуальной сетевой карты. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-boot-prio<replaceable>N</replaceable>=<replaceable>приоритет</replaceable></option></term> + <listitem><para> + Назначает приоритет для каждой NIC, что определяет порядок, + в котором соответствующий NIC используется для сетевой + загруки PXE. Значение приоритета - это число в диапазоне + от <literal>0</literal> до <literal>4</literal>. + Приоритет <literal>0</literal>, который является значением + по умолчанию, представляет наименьший приоритет. Приоритет + <literal>1</literal> - это наибольший приоритет, а + приоритеты <literal>3</literal> и <literal>4</literal> - + ниже. + </para><para> + Эта опция работает только когда используется загрузочный + ROM Intel PXE. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-promisc<replaceable>N</replaceable>=deny | allow-vms | allow-all</option></term> + <listitem><para> + Позволяет указать разрешен или запрещен неразборчивый + режим указанной виртуальной сетевой карты ВМ. Эта опция + имеет значение только для сетевого моста. + Допустимые значения: + </para><itemizedlist> + <listitem><para> + <literal>deny</literal> прячет любой траффик, не + предназначенный данной ВМ. Это значение по умолчанию. + </para></listitem> + <listitem><para> + <literal>allow-vms</literal> прячет весь траффик хоста, + но разрешает ВМ просматривать траффик других ВМ. + </para></listitem> + <listitem><para> + <literal>allow-all</literal> разрешает ВМ просматривать + весь траффик. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-bandwidth-group<replaceable>N</replaceable>=none | <replaceable>имя</replaceable></option></term> + <listitem><para> + Добавляет или удаляет назначение группы полосы пропускания + к указанной виртуальной сетевой карте. Допустимые значения: + </para><itemizedlist> + <listitem><para> + <literal>none</literal> удаляет любое текущее назначение + группы полосы пропускания из указанного виртуального + сетевого интерфейса. + </para></listitem> + <listitem><para> + <replaceable>имя</replaceable> добавляет назначение группы + полосы пропускания к указанному виртуальному сетевому + интерфейсу. + </para></listitem> + </itemizedlist><para> + Смотрите <xref linkend="network_bandwidth_limit" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bridge-adapter<replaceable>N</replaceable>=none | <replaceable>имя-устройства</replaceable></option></term> + <listitem><para> + Указывает интерфейс хоста используемого в указанном + виртуальном сетевом интерфейсе. Смотрите + <xref linkend="network_bridged" />. Используйте эту опцию + только если использована опция <option>--nic</option> для + включения сетевого моста для указанной виртуальной сетевой + карты. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--host-only-adapter<replaceable>N</replaceable>=none | <replaceable>имя-устройства</replaceable></option></term> + <listitem><para> + Указывает интерфейс сети хоста используемого в указанном + виртуальном сетевом интерфейсе. Смотрите + <xref linkend="network_hostonly" />. Используйте эту опцию + только если использована опция <option>--nic</option> для + включения сети хоста для указанной виртуальной сетевой + карты. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--intnet<replaceable>N</replaceable>=<replaceable>имя-сети</replaceable></option></term> + <listitem><para> + Указывает имя внутренней сети. Смотрите + <xref linkend="network_internal" />. Используйте эту опцию + только если использована опция <option>--nic</option> для + включения внутренней сети для указанной виртуальной сетевой + карты. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-network<replaceable>N</replaceable>=<replaceable>имя-сети</replaceable></option></term> + <listitem><para> + Указывает имя сети NAT, куда подключен адаптер. + Используйте эту опцию только если тип сети + <literal>natnetwork</literal>, а не <literal>nat</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-generic-drv<replaceable>N</replaceable>=<replaceable>драйвер-бэкенда</replaceable></option></term> + <listitem><para> + Позволяет получить доступ к редко используемым сетевым + подрежимам, таких как сети VDE и UDP туннель. + Используйте эту опцию, только если использована опция + <option>--nic</option> для включения generic сети для + указанной виртуальной сетевой карты. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mac-address<replaceable>N</replaceable>=auto | <replaceable>MAC-адрес</replaceable></option></term> + <listitem><para> + Указывает MAC адрес указанного сетевого адаптера ВМ. + По умолчанию, &product-name; назначает случайный MAC + адрес на каждый сетевой адаптер при создании ВМ. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-networking-nat"> + <title>Настройкт сети NAT</title> + <remark role="help-copy-synopsis"/> + <para> + В следующих опциях, используйте <replaceable>N</replaceable> + для указания определенного виртуального сетевого адаптера, + где нужно произвести изменения. + </para> + <variablelist> + <varlistentry> + <term><option>--nat-net<replaceable>N</replaceable>=default | <replaceable>сеть</replaceable></option></term> + <listitem><para> + Указывает диапазон IP адресов используемый в этой сети. + Смотрите <xref linkend="changenat" />. Используйте эту опцию + только если тип сети <literal>nat</literal>, а не + <literal>natnetwork</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-pf<replaceable>N</replaceable>=[<replaceable>имя</replaceable>],tcp | udp,[<replaceable>IP-хоста</replaceable>],<replaceable>порт-хоста</replaceable>,[<replaceable>IP-гостя</replaceable>],<replaceable>порт-гостя</replaceable></option></term> + <listitem><para> + Указывает используемое правило перенаправления портов NAT. + Смотрите <xref linkend="natforward" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-pf<replaceable>N</replaceable>=delete <replaceable>имя</replaceable></option></term> + <listitem><para> + Указывает правило перенаправления портов NAT для удаления. + Смотрите <xref linkend="natforward" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-tftp-prefix<replaceable>N</replaceable>=<replaceable>префикс</replaceable></option></term> + <listitem><para> + Задает префикс, используемый во встроенном TFTP сервере. + Например, можно использовать префикс, для указания, где + расположен загрузочный файл. Смотрите <xref linkend="nat-tftp" /> + и <xref linkend="nat-adv-tftp" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-tftp-file<replaceable>N</replaceable>=<replaceable>загрузочный-файл</replaceable></option></term> + <listitem><para> + Задает имя загрузочного файла TFTP. Смотрите + <xref linkend="nat-adv-tftp" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-tftp-server<replaceable>N</replaceable>=<replaceable>сервер-tftp</replaceable></option></term> + <listitem><para> + Задает адрес сервера TFTP, откуда загружаться. Смотрите + <xref linkend="nat-adv-tftp" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-bind-ip<replaceable>N</replaceable>=<replaceable>IP-адрес</replaceable></option></term> + <listitem><para> + Задает альтернативный IP адрес, на который привязывается + движок NAT. Смотрите <xref linkend="nat-adv-settings" />. + По умолчанию, движок NAT &product-name; перенаправляет пакеты TCP/IP + через интерфейс по умолчанию, назначенный TCP/IP стеком хоста. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-dns-pass-domain<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + Указывает, передает ли встроенный DHCP сервер имя домена + для разрешения сетевого имени. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-dns-proxy<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + Указывает, что движок NAT - это прокси для всех запросов DNS + из гостевых систем в DNS серверы хост-системы. Смотрите + <xref linkend="nat-adv-dns" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-dns-host-resolver<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + Указывает, что движок NAT использует механизм разрешения + хост-системы для обработки DNS запросов. Смотрите + <xref linkend="nat-adv-dns" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-localhostreachable<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + Указывает, что движок NAT разрешает траффик из гостя направленный на + 10.0.2.2 передавать в локальную петлю хоста, то есть localhost или 127.0.0.1. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-settings<replaceable>N</replaceable>=[<replaceable>mtu</replaceable>],[<replaceable>отправка-сокет</replaceable>],[<replaceable>прием-сокет</replaceable>],[<replaceable>отправка-tcp</replaceable>],[<replaceable>прием-tcp</replaceable>]</option></term> + <listitem><para> + Задает значения для настройки производительности NAT. + Смотрите <xref linkend="nat-adv-settings" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-alias-mode<replaceable>N</replaceable>=default | [log],[proxyonly],[sameports]</option></term> + <listitem><para> + Задает поведение ядра движка NAT: + </para><itemizedlist> + <listitem><para> + <literal>log</literal> включает журналирование + </para></listitem> + <listitem><para> + <literal>proxyonly</literal> выключает режим + псеводонимов и делает NAT прозрачным + </para></listitem> + <listitem><para> + <literal>sameports</literal> заставляет движок NAT + отправлять пакеты через тот же порт, с которого + они пришли + </para></listitem> + <listitem><para> + <literal>default</literal> выключает все режимы псевдонимов. + </para></listitem> + </itemizedlist><para> + Для более подробной информации смотрите + <xref linkend="nat-adv-alias" />. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-other-hardware"> + <title>Другие настройки оборудования</title> + <remark role="help-copy-synopsis"/> + <para> + Следующие опции позволяют настроить другое оборудование, такое + как последовательный порт, монитор, аудио устройство, USB порты, + буфер обмена и функционал Drag and Drop. + </para> + <variablelist> + <varlistentry> + <term><option>--mouse=ps2 | usb | usbtablet | usbmultitouch</option></term> + <listitem><para> + Задает режим мыши в ВМ. Допустимые значения: + <literal>ps2</literal>, <literal>usb</literal>, + <literal>usbtablet</literal> и <literal>usbmultitouch</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--keyboard=ps2 | usb</option></term> + <listitem><para> + Задает режим клавиатуры в ВМ. Допустимые значения: + <literal>ps2</literal> и <literal>usb</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uart<replaceable>N</replaceable>=off | <replaceable>I/O-база</replaceable> <replaceable>IRQ</replaceable></option></term> + <listitem><para> + Настраивает виртуальные последовательные порты ВМ. + <replaceable>N</replaceable> представляет модифицируемый + последовательный порт. Допустимые значения + <literal>off</literal>, отключающее порт или базу I/O и + IRQ. Для информации по значениям базы I/O и IRQ традиционных + COM портов смотрите <xref linkend="serialports" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uart-mode<replaceable>N</replaceable>=<replaceable>режим</replaceable></option></term> + <listitem><para> + Указывает, как &product-name; соединяет указанный + виртуальный последовательный порт к хост-системе, где + работает ВМ. Смотрите <xref linkend="serialports" />. + </para><para> + Убедитесь, что сначала настроили виртуальный последовательный + порт через опцию <option>--uart<replaceable>N</replaceable></option>. + </para><para> + Задайте один из следующих режимов соединения для каждого порта: + </para><itemizedlist> + <listitem><para> + <literal>disconnected</literal> показывает что, даже + если последовательный порт отображается в гостевой ВМ, + он не подключен. Это состояние подобно физическому + COM порту без подключенного кабеля. + </para></listitem> + <listitem><para> + <literal>server</literal> + <replaceable>имя-канала</replaceable> создает + указанный именованный канал или сокет локального + домена в хост системе и присоединяет виртуальное + последовательное устройство к нему. + </para><para> + В хост-системе Windows <replaceable>имя-канала</replaceable> - + это именованный канала с именем в следующем формате: + <literal>\\.\pipe\<replaceable>имя-канала</replaceable></literal>. + </para><para> + В хост-системе Linux, + <replaceable>имя-канала</replaceable> это сокет локального + домена. + </para></listitem> + <listitem><para> + <literal>client</literal> + <replaceable>имя-канала</replaceable> подключает + виртуальное последовательное устройство к указанному + именованному каналу или сокету локального домена. + </para><para> + Заметим, что именованный канал или сокет локального домена + должны уже существовать. + </para></listitem> + <listitem><para> + <literal>tcpserver</literal> + <replaceable>порт</replaceable> создает сокет TCP + с указанным портом TCP в хост-системе и подключает + виртуальное последовательное устройство к нему. + </para><para> + В UNIX-подобных системах используйте порты больше + 1024 для не-root пользователей. + </para></listitem> + <listitem><para> + <literal>tcpclient</literal> + <replaceable>имя-хоста</replaceable>:<replaceable>порт</replaceable> + поключает виртуальное последовательное устройство к + сокету TCP. + </para><para> + Заметим, что TCP сокет должен уже существовать. + </para></listitem> + <listitem><para> + <literal>file</literal> + <replaceable>имя-файла</replaceable> перенаправляет + вывод последовательного порта в указанный файл. + Убедитесь, что <replaceable>имя-файла</replaceable> - + это абсолютный путь к файлу в хост-системе. + </para></listitem> + <listitem><para> + <replaceable>имя-устройства</replaceable> задает имя + устройства физического аппаратного последовательного + порта в указанной хост-системе, куда подсоединяется + виртуальный последовательный порт. + </para><para> + Используйте этот режим для подключения физического + последовательного порта к ВМ. + </para><para> + В хост-системах Windows имя устройства это COM порт + такой как <literal>COM1</literal>. В хост-системах Linux + имя устройства подобно <filename>/dev/ttyS0</filename>. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--uart-type<replaceable>N</replaceable>=<replaceable>тип-UART</replaceable></option></term> + <listitem><para> + Настраивает тип UART для указанного виртуального последовательного + порта (<replaceable>N</replaceable>). Допустимые значения + <literal>16450</literal>, <literal>16550A</literal> и + <literal>16750</literal>. Значение по умолчанию + <literal>16550A</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--lpt-mode<replaceable>N</replaceable>=<replaceable>имя-устройства</replaceable></option></term> + <listitem><para> + Задает имя устройства используемого параллельного порта. + </para><para> + В хост-системах Windows используйте имя устройства как + <command>lpt1</command>. В хост-системах Linux, + используйте имя устройства как <filename>/dev/lp0</filename>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--lpt<replaceable>N</replaceable>=<replaceable>I/O-база</replaceable> <replaceable>IRQ</replaceable></option></term> + <listitem><para> + Задает базовый адрес I/O и IRQ параллельного порта. + </para><para> + Можно посмотреть базовый адрес I/O и IRQ, используемый + для параллельного порта, в менеджере устройств. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-controller=<replaceable>тип-контроллера</replaceable></option></term> + <listitem><para> + Задает аудио контроллер, используемый в ВМ. + Допустимые значения: + <literal>ac97</literal>, <literal>hda</literal> и + <literal>sb16</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-codec=<replaceable>тип-кодека</replaceable></option></term> + <listitem><para> + Указывает аудио кодек, используемый в ВМ. Допустимые + значения: <literal>stac9700</literal>, + <literal>ad1980</literal>, <literal>stac9221</literal> + и <literal>sb16</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-driver=<replaceable>тип</replaceable></option></term> + <listitem><para> + Указывает, что ВМ имеет поддержку аудио определенного типа. + Допустимые значения: + <literal>none</literal>, <literal>default</literal>, + <literal>null</literal>, <literal>dsound</literal>, + <literal>was</literal>, <literal>oss</literal>, + <literal>alsa</literal>, <literal>pulse</literal> и + <literal>coreaudio</literal>. + </para><para> + Заметим, что типы аудио зависят от операционной системы + хоста. Вывод справки по команде <command>VBoxManage + modifyvm</command> поможет определить поддерживаемые + типы аудио для вашей операционной системы. + </para> + <para> + Для обеспечения максимальной совместимости между хостами можно + использовать стандартный аудиодрайвер по + умолчанию. В этом случае, виртуальная машина автоматически выберет + наиболее подходящий аудиодрайвер для текущего доступного хоста. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-enabled=on|off</option></term> + <listitem><para> + Указывает, следует ли включить или отключить звук для виртуальной + машины. + </para> + <para> + Эта опция имеет приоритет над опциями --audio-in и --audio-out, + т.е. отключение звука с помощью этой опции приведет к полному отключению + как входного, так и выходного звука. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-in=on|off</option></term> + <listitem><para> + Указывает, включать или нет аудио захват из хост-системы. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-out=on|off</option></term> + <listitem><para> + Указывает, включать или нет воспроизведение аудио из + гостевой ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--clipboard-mode=<replaceable>значение</replaceable></option></term> + <listitem><para> + Указывает, как предоставляются данные буфера обмена + между гостевой ВМ и хост-системой. + Допустимые значения: <literal>disabled</literal>, + <literal>hosttoguest</literal>, + <literal>guesttohost</literal> и + <literal>bidirectional</literal>. Смотрите + <xref linkend="generalsettings" />. + </para><para> + Функционал буфера обмена доступен только если + Дополнения Гостевой ОС установлены в ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--drag-and-drop=<replaceable>значение</replaceable></option></term> + <listitem><para> + Указывает, как используется функция drag and drop между + хост-системой и ВМ. Допустимые значения: + <literal>disabled</literal>, + <literal>hosttoguest</literal>, + <literal>guesttohost</literal> и + <literal>bidirectional</literal>. Смотрите + <xref linkend="guestadd-dnd" />. + </para><para> + Функционал drag and drop доступен только если + Дополнения Гостевой ОС установлены в ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--monitor-count=<replaceable>количество</replaceable></option></term> + <listitem><para> + Позволяет настроить несколько мониторов. Смотрите + <xref linkend="settings-display" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--usb-ohci=on | off</option></term> + <listitem><para> + Включает или отключает виртуальный USB 1.1 контроллер ВМ. + Смотрите <xref linkend="settings-usb" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--usb-ehci=on | off</option></term> + <listitem><para> + Включает или отключает виртуальный USB 2.0 контроллер ВМ. + Смотрите <xref linkend="settings-usb" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--usb-xhci=on | off</option></term> + <listitem><para> + Включает или отключает виртуальный USB 3.0 контроллер ВМ. + Это наиболее эффективная опция если ВМ поддерживает его. + Смотрите <xref linkend="settings-usb" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--usb-rename=<replaceable>старое-имя</replaceable> <replaceable>новое-имя</replaceable></option></term> + <listitem><para> + Переименовывает виртуальный USB контроллер ВМ из + <replaceable>старое-имя</replaceable> в + <replaceable>новое-имя</replaceable>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-recording"> + <title>Настройки записи</title> + <remark role="help-copy-synopsis"/> + <para> + Следующие опции позволяют изменить настройки записи видео, + записи аудио или обоих. + </para> + <variablelist> + <varlistentry> + <term><option>--recording=on | off</option></term> + <listitem><para> + Включает или отключает запись сессии ВМ в файл WebM или + VP8. Когда установлен в <literal>on</literal>, запись + начинается при старте сессии ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-screens=all | <replaceable>ID-экрана</replaceable></option></term> + <listitem><para> + Позволяет указать записываемый экран ВМ. С каждого экрана + запись ведется в свой файл. Допустимые значения: + <literal>all</literal>, то есть запись со всех экранов + или один или несколько указанных экранов. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-file=<replaceable>имя-файла</replaceable></option></term> + <listitem><para> + Задает имя файла куда сохранять запись. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-max-size=<replaceable>МБ</replaceable></option></term> + <listitem><para> + Задает максимальный размер файла записанного видео в + мегабайтах. Когда файл достигает указанного размера, + запись останавливается. Если указано значение + <literal>0</literal>, запись продолжается пока не будет + остановлена вручную. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-max-time=<replaceable>секунды</replaceable></option></term> + <listitem><para> + Задает максимальное записываемое время в секундах. + При достижении указанного времени запись останавливается. + Если указано значение <literal>0</literal>, запись + продолжается пока не будет остановлена вручную. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-opts=<replaceable>ключ</replaceable>=<replaceable>значение</replaceable></option></term> + <listitem><para> + Задает дополнительные свойства записи видео как + разделенный запятыми список свойств в виде ключ-значение. + Например <literal>foo=bar,a=b</literal>. + </para><para> + Используйте эту опцию, только если вы опытный пользователь. + Информацию о ключах смотрите в <citetitle>Oracle VM + VirtualBox Programming Guide and Reference</citetitle>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-video-fps=<replaceable>кадров-в-сек</replaceable></option></term> + <listitem><para> + Задает максимальное количество записываемых видеокадров + в секунду (FPS). Запись игнорирует все кадры с более + высокой частотой. Если увеличить FPS, меньше кадров + будет проигнорировано но запись и размер файла с + записью увеличится. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-video-rate=<replaceable>битрейт</replaceable></option></term> + <listitem><para> + Задает битрейт видео в килобит в секунду. Если увеличить + битрейт, качество записи улучшится но и размер записанного + файла также увеличится. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-video-res=<replaceable>ширина</replaceable>x<replaceable>высота</replaceable></option></term> + <listitem><para> + Задает разрешение записанного видео (ширина и высота) + в пикселах. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-vrde"> + <title>Настройки удаленной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Следующие опции позволяют изменить поведение расширения + удаленного рабочего стола VirtualBox (VRDE). + </para> + <variablelist> + <varlistentry> + <term><option>--vrde=on | off</option></term> + <listitem><para> + Включает или отключает сервер VRDE. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=TCP/Ports=<replaceable>порт</replaceable></option></term> + <listitem><para> + <replaceable>порт</replaceable> - это порт или диапазон + портов на которые подключается сервер VRDE. Значения + <literal>default</literal> или <literal>0</literal> + используют порт <literal>3389</literal>. Это стандартный + порт RDP. + </para><para> + Также cмотрите описание опции <option>--vrde-port</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=TCP/Address=<replaceable>IP-адрес</replaceable></option></term> + <listitem><para> + <replaceable>IP-адрес</replaceable> - это IP адрес + интерфейса сети хоста, к которому подключается сервер + VRDE. Когда указана, сервер принимает подключения только + на интерфейс сети хоста с этим IP адресом. + </para><para> + Также cмотрите описание опции <option>--vrde-address</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=VideoChannel/Enabled=<replaceable>значение</replaceable></option></term> + <listitem><para> + Указывает включен ли видеоканал VRDP или нет. + <literal>1</literal> значит <literal>on</literal> и + <literal>0</literal> значит <literal>off</literal>. + Смотрите <xref linkend="vrde-videochannel" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=Quality=<replaceable>значение</replaceable></option></term> + <listitem><para> + Задает значение между 10% и 100% включительно. Она + представляет уровень сжатия JPEG в видеоканале сервера + VRDE. Меньшее значение приводит к худшему качеству JPEG + но более высокое сжатие. Смотрите + <xref linkend="vrde-videochannel" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=DownscaleProtection=<replaceable>значение</replaceable></option></term> + <listitem><para> + Включает или отключает функцию защиты от уменьшения + масштаба. Допустимые значения <literal>1</literal> + включающая функцию и <literal>0</literal>, отключающую ее. + </para><para> + Когда эта функция включена, &product-name; определяет + отображать ли видео: + </para><itemizedlist> + <listitem><para> + Когда размер видео соответствуют размеру теневого + буфера, видео рассматривается как полноэкранное и + отображается. + </para></listitem> + <listitem><para> + Когда размер видео между полным экраном и порогом + уменьшения масштаба, видео не отображается. Такое + видео может быть окном приложения, нечитаемым при + уменьшении масштаба. + </para></listitem> + </itemizedlist><para> + Когда эта функция отключена, все равно производится попытка + отобразить видео. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=Client/DisableDisplay=1</option></term> + <listitem><para> + Отключает функцию отображения сервера VRDE. + </para><para> + Для повторного включения этой функции, назначьте пустое + значение. Например, для включения функии отображения + укажите команду <command>VBoxManage modifyvm + --vrde-property=Client/DisableDisplay=</command>. + Смотрите <xref linkend="vrde-customization" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=DisableInput=1</option></term> + <listitem><para> + Отключает функцию ввода сервера VRDE. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=DisableAudio=1</option></term> + <listitem><para> + Отключает функцию аудио сервера VRDE. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=DisableUSB=1</option></term> + <listitem><para> + Отключает функцию USB сервера VRDE. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=Client/DisableClipboard=1</option></term> + <listitem><para> + Отключает функцию буфера обмена сервера VRDE. Для + включения этой функции, назначьте пустое значение. + Смотрите <xref linkend="vrde-customization" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=DisableUpstreamAudio=1</option></term> + <listitem><para> + Отключает функцию передачи аудио на сервер VRDE. + Для включения этой функции назначьте пустое значение. + Смотрите <xref linkend="vrde-customization" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=Client/DisableRDPDR=1</option></term> + <listitem><para> + Отключает функцию RDP перенаправления устройств для + смарт-карт сервера VRDE. Для включения этой функции + назначьте пустое значение. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=H3DRedirect/Enabled=1</option></term> + <listitem><para> + Включает функию перенаправления 3D сервера VRDE. Для + включения этой функции назначьте пустое значение. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=Security/Method=<replaceable>значение</replaceable></option></term> + <listitem><para> + Указывает следующую информаицю, требуемую для подключения: + </para><itemizedlist> + <listitem><para> + <literal>Negotiate</literal> показывает, что разрешены + подключения, имеющие и расширенную (TLS) и стандартную + безопасность RDP. Метод безопасности согласуется с + клиентом. Это значение по умолчанию. + </para></listitem> + <listitem><para> + <literal>RDP</literal> показывает, что принимается только + подключение, имеющее стандартную безопасность RDP. + </para></listitem> + <listitem><para> + <literal>TLS</literal> показывает, что принимается только + подключение, имеющее расширенную безопасность RDP. Клиент + должен поддерживать TLS. + </para></listitem> + </itemizedlist><para> + Смотрите <xref linkend="vrde-crypt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=ServerCertificate=<replaceable>значение</replaceable></option></term> + <listitem><para> + Задает абсолютный путь к сертификату сервера. Смотрите + <xref linkend="vrde-crypt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=ServerPrivateKey=<replaceable>значение</replaceable></option></term> + <listitem><para> + Задает абсолютный путь к приватному ключу сервера. Смотрите + <xref linkend="vrde-crypt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=CACertificate=<replaceable>значение</replaceable></option></term> + <listitem><para> + Задает абсолютный путь к корневому самоподписанному + сертификату. Смотрите <xref linkend="vrde-crypt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property Audio/RateCorrectionMode=<replaceable>значение</replaceable></option></term> + <listitem><para> + Задает режим подключения аудио или путь к файлу аудио + журнала. Допустимые значения: + </para><itemizedlist> + <listitem><para> + <literal>VRDP_AUDIO_MODE_VOID</literal> - + отсутствие режима. Используйте это значение для + снятия используемого режима. + </para></listitem> + <listitem><para> + <literal>VRDP_AUDIO_MODE_RC</literal> - режим + коррекции скорости. + </para></listitem> + <listitem><para> + <literal>VRDP_AUDIO_MODE_LPF</literal> - режим + низкочастотного фильтра. + </para></listitem> + <listitem><para> + <literal>VRDP_AUDIO_MODE_CS</literal> - режим + синхронизации с клиентом для предотвращения + переполнения или недозаполнености очереди клиента. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=LogPath=<replaceable>значение</replaceable></option></term> + <listitem><para> + Задает абсолютный путь к файлу аудио журнала. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-extpack=default | <replaceable>имя</replaceable></option></term> + <listitem><para> + Задает библиотеку, используемую для удаленного доступа + к ВМ. Значение <literal>default</literal> использует + код RDP, который является частью пакета расширения + &product-name;. + </para><para> + Для использования модуля VRDE в VNC, укажите + <literal>VNC</literal>. Смотрите + <xref linkend="otherextpacks"/>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-port=default | <replaceable>порт</replaceable></option></term> + <listitem><para> + <replaceable>порт</replaceable> - это порт или диапазон + портов на которые подключается сервер VRDE. Значение + <literal>default</literal> или <literal>0</literal> + использует порт <literal>3389</literal>, который + является стандартным портом RDP. + </para><para> + Можно указать разделенный запятыми список портов или + диапазонов портов. Используйте дефис между двумя + номерами портов для задания диапазона. Сервер VRDE + подключается только к одному доступному порту из списка. + В один и тот же момент, только одна машина может + использовать данный порт. Например, опция + <option>--vrde-port=5000,5010-5012</option> указывает, + что сервер может подключиться на один из следующих портов: + <literal>5000</literal>, <literal>5010</literal>, + <literal>5011</literal> или <literal>5012</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-address=<replaceable>IP-адрес</replaceable></option></term> + <listitem><para> + Задает IP адрес интерфейса сети хоста, на который + подключается сервер VRDE. Если указать IP адрес, сервер + VRDE принимает подключения только с указанного + интерфейса сети хоста. + </para><para> + Используйте эту опцию для указания, что сервер VRDP + должен принимать IPv4, IPv6 или оба тип соединений: + </para><itemizedlist> + <listitem><para> + <emphasis role="bold">Только IPv4:</emphasis> + Используйте опцию + <option>--vrde-address="0.0.0.0"</option>. + </para></listitem> + <listitem><para> + <emphasis role="bold">Только IPv6:</emphasis> + Используйте опцию + <option>--vrde-address="::"</option>. + </para></listitem> + <listitem><para> + <emphasis role="bold">И IPv6 и IPv4:</emphasis> + Используйте опцию <option>--vrde-address=""</option>. + Это значение по умолчанию. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-auth-type=null | external | guest</option></term> + <listitem><para> + Указывает использовать ли авторизацию и как ее проводить. + Смотрите <xref linkend="vbox-auth" />. Допустимые значения: + </para><itemizedlist> + <listitem><para> + <literal>null</literal> - без аутентификации. + </para></listitem> + <listitem><para> + <literal>external</literal> - внешняя аутентификация + через библиотеку аутентификации. + </para></listitem> + <listitem><para> + <literal>guest</literal> - аутентификация через + гостевые пользовательские учетные записи. Этот + неподдерживаемый метод требует установки Дополнений + Гостевой ОС в ВМ. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-auth-library=default | <replaceable>имя</replaceable></option></term> + <listitem><para> + Задает библиотеку, используемую для аутентификации RDP. + Библиотека по умолчанию для внешней аутентификации + <filename>VBoxAuth</filename>. Смотрите + <xref linkend="vbox-auth" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-multi-con=on | off</option></term> + <listitem><para> + Включает или отключает функцию множественных подключений + к серверу VRDE, если поддерживается. Смотрите + <xref linkend="vrde-multiconnection" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-reuse-con=on | off</option></term> + <listitem><para> + Задает поведение сервера VRDE когда множественные + подключения отключены. Когда значение + <literal>on</literal>, сервер разрешает подключение + нового клиента и разрывает существующее. Когда значение + <literal>off</literal>, новое подключение не принимается + если клиент уже подключен к серверу. Это значение + по умолчанию. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-video-channel=on | off</option></term> + <listitem><para> + Включает перенаправление видео, если поддерживается сервером + VRDE. Смотрите <xref linkend="vrde-videochannel" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-video-channel-quality=<replaceable>процент</replaceable></option></term> + <listitem><para> + Задает качество видео при перенаправлении как величина + от 10 до 100 процентов. Процент представляет уровень + сжатия JPEG, где меньшие значения ухудшают качество, + но обеспечивают более высокое сжатие. Смотрите + <xref linkend="vrde-videochannel" />. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-teleport"> + <title>Настройки портирования</title> + <remark role="help-copy-synopsis"/> + <para> + Следующие опции позволяют настроить машину как цель + портирования. Смотрите <xref linkend="teleporting" />. + </para> + <variablelist> + <varlistentry> + <term><option>--teleporter=on | off</option></term> + <listitem><para> + Включает или выключает портирование. Когда включено, + машина стартует и ждет получения запроса на портирование + из сети вместо нормальной загрузки. + </para><para> + Запросы на портирование принимаются на порт и адрес, + указанный в следующих параметрах: + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--teleporter-port=<replaceable>порт</replaceable></option></term> + <listitem><para> + Задает порт, который слушает ВМ для получения запросов + на портирование из другой ВМ. + <replaceable>порт</replaceable> - это любой свободный + номер TCP/IP порта, такой как <literal>6000</literal>. + Необходимо также указать опцию <option>--teleporter</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--teleporter-address=<replaceable>IP-адрес</replaceable></option></term> + <listitem><para> + Задает IP адрес, который слушает ВМ для получения + запросов на портирование из другой ВМ. + <replaceable>IP-адрес</replaceable> - это любой IP + адрес или имя хоста. Он указывает сокет TCP/IP для + подключения. IP адрес по умолчанию + <literal>0.0.0.0</literal>, который представляет + любой IP адрес. Необходимо также указать опцию + <option>--teleporter</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--teleporter-password=<replaceable>пароль</replaceable></option></term> + <listitem><para> + Задает пароль, используемый для аутентификации. Когда + указан, запрос на портирование успешен только тогда, когда + пароль в исходной машине такой же, как и указанный. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--teleporter-password-file=<replaceable>имя-файла</replaceable></option></term> + <listitem><para> + Задает файл, содержащий пароль для использования в + аутентификации. Когда указан, запрос на портирование + успешен только тогда, когда пароль в исходной машине + такой же, как и в указанном файле. Значение + <literal>stdin</literal> читает пароль из стандартного + потока ввода. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpuid-portability-level=<replaceable>уровень</replaceable></option></term> + <listitem> + <para> + Ограничивает способности виртуального ЦПУ, которые + &product-name; представляет гостевой ОС использую правила + портативности. Более высокие целые значения означают + более ограниченное поведение. Уровень по умолчанию + <literal>0</literal> показывает, что весь поддерживаемый + хостом вируализированный функционал доступен гостевой + системе. Значение <literal>3</literal> подавляет + большинство функций. Значения <literal>1</literal> + и <literal>2</literal> представляют ограничения между + предыдущими уровнями. Поведение может меняться в + зависимости от версии продукта. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpuid-set=<replaceable>лист</replaceable>[:<replaceable>подлист</replaceable>] + <replaceable>eax</replaceable> <replaceable>ebx</replaceable> <replaceable>ecx</replaceable> <replaceable>edx</replaceable></option></term> + <listitem> + <para> + Опытные пользователи используют эту настройку перед + операцией портирования (фактически перед запуском ВМ) + для ограничения способностей виртуального ЦПУ, которые + &product-name; предоставляет гостевой операционной + системе. Это должно быть запущено и на исходной и на + целевой машинах, вовлеченных в процесс портирования и + определяет, что гостевая система увидит когда выполняет + машинную инструкцию CPUID. Это может помочь с неправильным + поведением приложений, которые неправильно предполагают, + что присутствуют определенные способности ЦПУ. + Значение параметра зависит от оборудования. Обратитесь + к документации AMD или Intel. + </para><para> + Значения <replaceable>лист</replaceable>, + <replaceable>подлист</replaceable> (необязательно), + <replaceable>eax</replaceable>, <replaceable>ebx</replaceable>, + <replaceable>ecx</replaceable> и <replaceable>edx</replaceable> + - это целые числа данные в шестнадцатиричном формате, то есть + используя основание 16 без какого-либо префикса. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpuid-remove=<replaceable>лист</replaceable>[:<replaceable>подлист</replaceable>]</option></term> + <listitem> + <para> + Удаляет подстройку, установленную через <option>--cpuid-set</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpuid-remove-all</option></term> + <listitem> + <para> + Удаляет все подстройки, установленные через <option>--cpuid-set</option>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-debugging"> + <title>Настройки отладки</title> + <remark role="help-copy-synopsis"/> + <para> + Используйте следующие опции только для низкоуровневой + отладки ВМ. Эти опции только для опытных пользователей. + </para> + <variablelist> + <varlistentry> + <term><option>--tracing-enabled=on | off</option></term> + <listitem><para> + Включает или отключает буфер трассировки. Заметим, что + когда указан, буфер трассировки потребляет память и + добавляет накладные расходы. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tracing-config=<replaceable>строка-настроек</replaceable></option></term> + <listitem><para> + Включает конфигурацию трассировки, определяющую группу + включенных точек трассировки. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tracing-allow-vm-access=on | off</option></term> + <listitem><para> + Включает или отключает доступ ВМ к буферу трассировки. + Значение по умолчанию <literal>off</literal>, что + запрещает доступ. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-usbcardreader"> + <title>Настройки USB картридера</title> + <remark role="help-copy-synopsis"/> + <para> + Следующие опции задают доступ гостевого окружения к USB картридеру. + USB картридер может получить доступ к данным карт памяти, таких + как CompactFlash (CF), Secure Digital (SD) и MultiMediaCard (MMC). + </para> + <variablelist> + <varlistentry> + <term><option>--usb-card-reader=on | off</option></term> + <listitem><para> + Включает или отключает интерфейс USB картридера. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-autostart"> + <title>Автостарт ВМ в течение загрузки хост-системы</title> + <para> + Следующие опции позволяют настроить функцию автостарта ВМ, + которая автоматически стартует ВМ во время загрузки хост-системы. + Требуется произвести некоторые настройки хост-системы перед + использованием этой функции. Смотрите <xref linkend="autostart" />. + </para> + <remark role="help-copy-synopsis"/> + <variablelist> + <varlistentry> + <term><option>--autostart-enabled=on | off</option></term> + <listitem><para> + Включает или отключает автостарт ВМ во время загрузки + хост-системы для указанного пользователя. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--autostart-delay=<replaceable>секунды</replaceable></option></term> + <listitem><para> + Задает количество секунд, по истечении которых после + загрузки хост-системы, ВМ стартует. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-pcipassthrough"> + <title>Настройки сквозного режима PCI</title> + <para> + Следующие опции позволяют настроить функцию сквозного режима PCI, + которая на настоящий момент не доступна в &product-name;. + Планируется вернуть данный функционал в будущем. + </para> + <remark role="help-copy-synopsis"/> + <variablelist> + <varlistentry> + <term><option>--pci-attach=<replaceable>PCI-адрес-хоста</replaceable>[@<replaceable>гостевой-PCI-адрес-шины</replaceable>]</option></term> + <listitem><para> + Подключает указанный сетевой контроллер PCI хоста к гостевой + ВМ. Можно опционально указать шину PCI в гостевой ВМ, куда + подключать контроллер. +<!-- See <xref linkend="pcipassthrough" />. --> + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--pci-detach=<replaceable>PCI-адрес-хоста</replaceable></option></term> + <listitem><para> + Отключает указанный сетевой контроллер PCI из + подключенной PCI шины гостевой ВМ. +<!-- See <xref linkend="pcipassthrough" />. --> + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-testing"> + <title>Тестирование (ValidationKit / Bootsector)</title> + <para> + Эти опции для настройки функционала тестирования VMM устройств и + почти экслюзивно используются bootsector тестами в ValidationKit. + </para> + <remark role="help-copy-synopsis"/> + <variablelist> + <varlistentry> + <term><option>--testing-enabled=on | off</option></term> + <listitem><para>Включен функционал тестирования VMMDev. Для подробной информации смотрите VMMDevTesting.h. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--testing-mmio=on | off</option></term> + <listitem><para>Включена область MMIO для функционала тестирования VMMDev.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--testing-cfg-dword<replaceable>idx</replaceable>=<replaceable>значение</replaceable></option></term> + <listitem><para> + Это задает один из 10 DWORD значений конфигурации. + <replaceable>idx</replaceable> должен быть в диапазоне от 0 до 9. + <replaceable>значение</replaceable> ограничено 32 битами (DWORD). + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда изменяет описание для ВМ + <filename>ol7</filename>. + </para> +<screen>$ VBoxManage modifyvm ol7 --description "Oracle Linux 7 with UEK4"</screen> + <para> + Следующая команда включает поддержку протокола удаленного + рабочего стола VirtualBox (VRDP) для ВМ <filename>ol7</filename>. + </para> +<screen>$ VBoxManage modifyvm ol7 --vrde on</screen> + </refsect1> + + <refsect1> + <title>Смотрите также</title> + <para> + <xref linkend="vboxmanage-showvminfo" />, + <xref linkend="vboxmanage-controlvm" />, + <xref linkend="vboxmanage-createvm" />, + <xref linkend="vboxmanage-startvm" /> + <xref linkend="vboxmanage-list" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-movevm.xml b/doc/manual/ru_RU/man_VBoxManage-movevm.xml new file mode 100644 index 00000000..889e34ef --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-movevm.xml @@ -0,0 +1,113 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage movevm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-movevm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage movevm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-movevm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-movevm</refname> + <refpurpose>перемещает виртуальную машину в новое расположение в хост-системе</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-movevm"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage movevm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg>--type=basic</arg> + <arg>--folder=<replaceable>имя-папки</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage movevm</command> перемещает + виртуальную машину (ВМ) в новое расположение в хост-системе. + </para> + <para> + Когда перемещена, все файлы, связанные с ВМ, такие как файлы + настроек и файлы образов дисков, перемещаются в новое расположение. + Конфигурация &product-name; обновляется автоматически. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>имя-ВМ</replaceable></term> + <listitem><para> + Указывает Универсальный Уникальный Идентификатор (UUID) + или имя ВМ для перемещения. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--type=basic</option></term> + <listitem><para> + Задает тип операции перемещения. Пока что <literal>basic</literal> + является единственным распознаваемым значением и также + является значением по умолчанию, если не указан. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--folder=<replaceable>имя-папки</replaceable></option></term> + <listitem><para> + Указывает полный или относительный путь к новому + расположению в файловой системе хоста. Позволяется + не указывать эту опцию или указать текущее расположение. + В этом случае производится перемещение образов дисков + и других частей ВМ в это расположение, если они находятся + в других местах. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда перемещает ВМ <filename>ol7</filename> в новое + расположение в хост-системе. + </para> +<screen>$ VBoxManage movevm ol7 --folder "/home/testuser/vms" --type basic +0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100% +Машина успешно перемещена в /home/testuser/vms</screen> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-natnetwork.xml b/doc/manual/ru_RU/man_VBoxManage-natnetwork.xml new file mode 100644 index 00000000..850fcb25 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-natnetwork.xml @@ -0,0 +1,367 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage natnetwork +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-natnetwork" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage natnetwork</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-natnetwork</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-natnetwork</refname> + <refpurpose>создает, изменяет или управляет сетью NAT</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-natnetwork-add"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage natnetwork add</command> + <group> + <arg choice="plain">--disable</arg> + <arg choice="plain">--enable</arg> + </group> + <arg choice="req">--netname=<replaceable>имя</replaceable></arg> + <arg choice="req">--network=<replaceable>сеть</replaceable></arg> + <arg>--dhcp=on|off</arg> + <arg>--ipv6=on|off</arg> + <arg>--loopback-4=<replaceable>правило</replaceable></arg> + <arg>--loopback-6=<replaceable>правило</replaceable></arg> + <arg>--port-forward-4=<replaceable>правило</replaceable></arg> + <arg>--port-forward-6=<replaceable>правило</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-natnetwork-list"> + <command>VBoxManage natnetwork list</command> + <arg><replaceable>шаблон-фильтра</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-natnetwork-modify"> + <command>VBoxManage natnetwork modify</command> + <arg>--dhcp=on|off</arg> + <group> + <arg choice="plain">--disable</arg> + <arg choice="plain">--enable</arg> + </group> + <arg choice="req">--netname=<replaceable>имя</replaceable></arg> + <arg choice="req">--network=<replaceable>сеть</replaceable></arg> + <arg>--ipv6=on|off</arg> + <arg>--loopback-4=<replaceable>правило</replaceable></arg> + <arg>--loopback-6=<replaceable>правило</replaceable></arg> + <arg>--port-forward-4=<replaceable>правило</replaceable></arg> + <arg>--port-forward-6=<replaceable>правило</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-natnetwork-remove"> + <command>VBoxManage natnetwork remove</command> + <arg choice="req">--netname=<replaceable>имя</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-natnetwork-start"> + <command>VBoxManage natnetwork start</command> + <arg choice="req">--netname=<replaceable>имя</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-natnetwork-stop"> + <command>VBoxManage natnetwork stop</command> + <arg choice="req">--netname=<replaceable>имя</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage natnetwork</command> позволяет + создавать, изменять и управлять сетью NAT. + </para> + <para> + Сети NAT используют службу преобразования сетевых адресов (NAT). + Служба группирует системы в сеть и предотвращает прямой доступ + внешних систем к системам внутри сети. Служба также позволяет + системам в сети общаться друг с другом и с внешними системами + посредством TCP и UDP через IPv4 и IPv6. + </para> + <para> + Служба NAT подключена к внутренней сети. Чтобы ВМ использовала + службу NAT, необходимо подключить ВМ к внутренней сети. Задайте + имя внутренней сети когда создаете службу NAT. Заметим, что + внутренняя сеть создается если она еще не существует. + </para> + <refsect2 id="vboxmanage-natnetwork-add"> + <title>Добавить службу сети NAT</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage natnetwork add</command> создает + новый интерфейс внутренней сети и добавляет службу сети NAT. + Вы должны использовать эту команду перед тем как подключать + ВМ к сети NAT. + </para> + <variablelist> + <varlistentry> + <term><option>--disable</option></term> + <listitem><para> + Отключает службу сети NAT. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--enable</option></term> + <listitem><para> + Включает службу сети NAT. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--netname=<replaceable>имя</replaceable></option></term> + <listitem><para> + Задает имя нового интерфейса внутренней сети в ОС хоста. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--network</option></term> + <listitem><para> + Указывает статический адрес или сетевой адрес DHCP и + маску интерфейса службы NAT. По умолчанию, это значение + указывает статический сетевой адрес. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dhcp</option></term> + <listitem><para> + Включает или отключает сервер DHCP, который указывается + через опцию <option>--netname</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ipv6</option></term> + <listitem><para> + Включает или отключает IPv6. По умолчанию, IPv6 отключен, + а IPv4 включен. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--loopback-4=<replaceable>правило</replaceable></option></term> + <listitem><para> + Включает интерфейс локальной петли IPv4, используя + указанное правило. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--loopback-6=<replaceable>правило</replaceable></option></term> + <listitem><para> + Включает интерфейс локальной петли IPv6, используя + указанное правило. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--port-forward-4=<replaceable>правило</replaceable></option></term> + <listitem><para> + Включает перенаправление портов IPv4 используя правило, + указанное в <replaceable>правило</replaceable>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--port-forward-6=<replaceable>rule</replaceable></option></term> + <listitem><para> + Включает перенаправление портов IPv6 используя правило, + указанное в <replaceable>правило</replaceable>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-natnetwork-remove"> + <title>Удалить службу сети NAT</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage natnetwork remove</command> + удаляет указанную службу сети NAT. + </para> + <variablelist> + <varlistentry> + <term><option>--netname=<replaceable>имя</replaceable></option></term> + <listitem><para> + Задает имя удаляемой службы сети NAT. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-natnetwork-start"> + <title>Запустить службу сети NAT</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage natnetwork start</command> + запускает службу сети NAT и любой связанный сервер DHCP. + </para> + <variablelist> + <varlistentry> + <term><option>--netname=<replaceable>имя</replaceable></option></term> + <listitem><para> + Задает имя запускаемой службы сети NAT. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-natnetwork-stop"> + <title>Остановить службу сети NAT</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage natnetwork stop</command> + останавливает службу сети NAT и любой связанный сервер DHCP. + </para> + <variablelist> + <varlistentry> + <term><option>--netname=<replaceable>имя</replaceable></option></term> + <listitem><para> + Задает имя останавливаемой службы сети NAT. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-natnetwork-list"> + <title>Показать все службы сети NAT</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage natnetwork list</command> показывает + все службы сети NAT. Можно использовать шаблон для отображения + подмножества служб сетей NAT. + </para> + <variablelist> + <varlistentry> + <term><replaceable>шаблон-фильтра</replaceable></term> + <listitem><para> + Указывает необязательный шаблон фильтра. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-natnetwork-modify"> + <title>Изменить настройки службы сети NAT</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage natnetwork modify</command> + изменяет настройки существующего интерфейса внутренней + сети. + </para> + <variablelist> + <varlistentry> + <term><option>--disable</option></term> + <listitem><para> + Отключает службу сети NAT. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--enable</option></term> + <listitem><para> + Включает службу сети NAT. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--netname=<replaceable>имя</replaceable></option></term> + <listitem><para> + Задает имя нового интерфейса внутренней сети в ОС хоста. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--network</option></term> + <listitem><para> + Указывает статический или DHCP сетевой адрес и маску + интерфейса службы NAT. По умолчанию это значение + указывает статический сетевой адрес. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dhcp</option></term> + <listitem><para> + Включает или отключает сервер DHCP, указанный через + опцию <option>--netname</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ipv6</option></term> + <listitem><para> + Включает или отключает IPv6. По умолчанию IPv6 отключен, а + IPv4 включен. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--loopback-4=<replaceable>правило</replaceable></option></term> + <listitem><para> + Включает интерфейс локальной петли IPv4, используя + указанное правило. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--loopback-6=<replaceable>правило</replaceable></option></term> + <listitem><para> + Включает интерфейс локальной петли IPv6, используя + указанное правило. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--port-forward-4=<replaceable>правило</replaceable></option></term> + <listitem><para> + Включает перенаправление портов IPv4, используя правило, + указанное в <replaceable>правило</replaceable>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--port-forward-6=<replaceable>rule</replaceable></option></term> + <listitem><para> + Включает перенаправление портов IPv6, используя правило, + указанное в <replaceable>правило</replaceable>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + Следующая команда показывает как создать сеть NAT для + внутренней сети <literal>natnet1</literal>, использующей + сетевой адрес и маску <literal>192.168.15.0/24</literal> + интерфейса службы NAT. В этой статической конфигурации, + по умолчанию шлюзу назначен IP адрес <literal>192.168.15.1</literal>. + Заметим, что этот IP адрес - это следующий адрес после адреса, + указанного опцией <option>--network</option>. + </para> +<screen>$ VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable</screen> + <para> + Следующая команда показывает как добавить сервер DHCP к + сети NAT <literal>natnet1</literal> после создания: + </para> +<screen>$ VBoxManage natnetwork modify --netname natnet1 --dhcp on</screen> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-registervm.xml b/doc/manual/ru_RU/man_VBoxManage-registervm.xml new file mode 100644 index 00000000..76688b7a --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-registervm.xml @@ -0,0 +1,102 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage registervm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-registervm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage registervm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-registervm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-registervm</refname> + <refpurpose>регистрирует виртуальную машину</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-registervm"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage registervm</command> + <arg choice="req"><replaceable>имя-файла</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage registervm</command> позволяет + создать виртуальную машину (ВМ) путем импорта XML файла + конфигурации машины в &product-name;. У ВМ не может быть + такой же UUID как и у машины, уже зарегистрированной в + &product-name;. Убедитесь перед регистрацией, что XML файл + конфигурации машины находится в папке машины. + </para> + <note> + <para> + При создании ВМ с помощью команды <command>VBoxManage + createvm</command> можно указать опцию <option>--register</option> + для регистрации ВМ после создания. + </para> + </note> + <variablelist> + <varlistentry> + <term><replaceable>имя-файла</replaceable></term> + <listitem><para> + Задает XML файл конфигурации машины. Этот файл + имеет расширение <filename>.vbox</filename>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда регистрирует ВМ, называемую <literal>vm2</literal>. + XMl файл конфигурации машины для этой ВМ расположен в папке машины + по умолчанию. + </para> +<screen>$ VBoxManage registervm "/home/user/VirtualBox VMs/vm2/vm2.vbox"</screen> + </refsect1> + + <refsect1> + <title>Смотрите также</title> + <para> + <xref linkend="vboxmanage-createvm"/>, + <xref linkend="vboxmanage-unregistervm" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-setextradata.xml b/doc/manual/ru_RU/man_VBoxManage-setextradata.xml new file mode 100644 index 00000000..bb7e9c0f --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-setextradata.xml @@ -0,0 +1,122 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage setextradata +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-setextradata" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage setextradata</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-setextradata</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-setextradata</refname> + <refpurpose>устанавливает значение ключа связанного с виртуальной машиной или конфигурацией</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-setextradata"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage setextradata</command> + <group choice="req"> + <arg choice="plain">global</arg> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="req"><replaceable>ключ</replaceable></arg> + <arg><replaceable>значение</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage setextradata</command> позволяет + задать значение ключа связанного с виртуальной машиной (ВМ) + или с конфигурацией &product-name;. + </para> + <variablelist> + <varlistentry> + <term><literal>global</literal></term> + <listitem><para> + Устанавливает информацию о конфигурации а не ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>имя-ВМ</replaceable></term> + <listitem><para> + Задает Универсальный Уникальный Идентификатор (UUID) или + имя ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>ключ</replaceable></term> + <listitem><para> + Задает ключ, для которого задается значение. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>значение</replaceable></term> + <listitem><para> + Задает значение ключа. Если не указывается значение, ключ + удаляется. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + Следующая команда устанавливает значение ключа + <literal>installdate</literal> для ВМ <literal>Fedora5</literal> + в <literal>2019.01.01</literal>: + </para> +<screen>$ VBoxManage setextradata Fedora5 installdate 2019.01.01</screen> + <para> + Следующая команда удаляет значение ключа + <literal>installdate</literal> из ВМ + <literal>Fedora5</literal>: + </para> +<screen>$ VBoxManage setextradata Fedora5 installdate</screen> + </refsect1> + + <refsect1> + <title>Смотрите также</title> + <para> + <xref linkend="vboxmanage-getextradata" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-setproperty.xml b/doc/manual/ru_RU/man_VBoxManage-setproperty.xml new file mode 100644 index 00000000..354e5d70 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-setproperty.xml @@ -0,0 +1,232 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage setproperty +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-setproperty" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage setproperty</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-setproperty</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-setproperty</refname> + <refpurpose>изменение глобальных настроек</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <cmdsynopsis id="synopsis-vboxmanage-setproperty"> + <command>VBoxManage setproperty</command> + <arg choice="req"><replaceable>имя-свойства</replaceable></arg> + <arg choice="req"><replaceable>значение-свойства</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage setproperty</command> позволяет + изменить глобальные настройки влияющие на всю инсталляцию + &product-name;. Некоторые из этих настроек соответствуют + настройкам в диалоге <emphasis role="bold">Настройки</emphasis> + в Менеджере VirtualBox. + </para> + <para> + Доступны следующие свойства: + </para> + <variablelist> + <varlistentry> + <term><literal>autostartdbpath</literal></term> + <listitem><para> + Задает путь к базе данных автостарта. Допустимые значения + <literal>null</literal>, которое отключает базу данных + автостарта или имя папки, содержащую базу данных. + Смотрите <xref linkend="autostart" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>defaultfrontend</literal></term> + <listitem><para> + Задает глобальный фронтенд ВМ по умолчанию. Допустимые + значения <literal>default</literal>, которое указывает + фронтенд по умолчанию, или имя используемого фронтенда. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>hwvirtexclusive</literal></term> + <listitem><para> + Указывает, использует ли &product-name; эксклюзивно + расширение аппаратной виртуализации Intel VT-x или AMD-V + системного процессора хоста. Смотрите <xref linkend="hwvirt" />. + </para><para> + Допустимы следующие значения: + </para><itemizedlist> + <listitem><para> + <literal>on</literal> позволяет &product-name; + использовать эксклюзивно эти расширения. Это значение + по умолчанию. + </para></listitem> + <listitem><para> + <literal>off</literal> совместно использует эти + расширения с другими гипервизорами, работающими + одновременно. Заметим, что отключение этой + настройки имеет негативное воздействие на + производительность. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><literal>language</literal></term> + <listitem><para> + Указывает язык пользователя для перевода сообщений API. + Допустимые значения <literal>C</literal>, что означает + отсутствие перевода или код языка в форме <literal>ll</literal> + или <literal>ll_CC</literal>, где <literal>ll</literal> - + это двухбуквенный код языка в нижнем регистре и + <literal>CC</literal> - это двухбуквенный код страны в + верхнем регистре. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>logginglevel</literal></term> + <listitem><para> + Задает детали журналирования VBoxSVC в режиме выпуска. + Смотрите <ulink url="http://www.virtualbox.org/wiki/VBoxLogging" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>loghistorycount</literal></term> + <listitem><para> + Указывает количество оставляемых циклических журналов ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>machinefolder</literal></term> + <listitem><para> + Задает папку по умолчанию куда сохраняются определения + виртуальных машин (ВМ). Допустимые значения + <literal>default</literal>, который указывает папку + хранилища по умолчанию или имя используемой папки. + Смотрите <xref linkend="vboxconfigdata" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>proxymode</literal></term> + <listitem><para> + Настраивает режим сервера прокси HTTP. Допустимые значения: + </para><variablelist> + <varlistentry> + <term><literal>manual</literal></term> + <listitem><para> + Настраивает вручную URL сервера прокси HTTP, + с помощью значения свойства <literal>proxyurl</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>noproxy</literal></term> + <listitem><para> + Не использовать сервер прокси HTTP. Используется + прямое соединение к интернету. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>system</literal></term> + <listitem><para> + Автоматически определить настройки прокси для сети + хоста. Это значение по умолчанию. + </para></listitem> + </varlistentry> + </variablelist></listitem> + </varlistentry> + <varlistentry> + <term><literal>proxyurl</literal></term> + <listitem><para> + Задает URL для сервера прокси HTTP при использовании + ручной настройки через установку свойства + <literal>proxymode</literal> в <literal>manual</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>vrdeauthlibrary</literal></term> + <listitem><para> + Указывает используемую библиотеку если настроена + внешняя аутентификация для определенной ВМ. Допустимые + значения <literal>default</literal>, которая задает + библиотеку по умолчанию или имя используемой библиотеки. + Смотрите <xref linkend="vbox-auth" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>vrdeextpack</literal></term> + <listitem><para> + Задает библиотеку, реализующую расширение удаленного + рабочего стола VirtualBox (RDE). Допустимые значения + <literal>null</literal>, которое отключает RDE или имя + используемой библиотеки. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>websrvauthlibrary</literal></term> + <listitem><para> + Указывает, библиотеку, используемую веб службой для + аутентификации пользователей. Допустимые значения + <literal>default</literal>, которое задает библиотеку + по умолчанию, <literal>null</literal>, которое отключает + аутентификацию или имя используемой библиотеки. Для + дополнительной информации о веб службе &product-name; + Смотрите <xref linkend="VirtualBoxAPI" />. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда настраивает &product-name; для использования + указанного сервера прокси HTTP. + </para> +<screen>$ VBoxManage setproperty proxymode manual +$ VBoxManage setproperty proxyurl "http://myproxy.com:8080"</screen> + </refsect1> + + <refsect1> + <title>Смотрите также</title> + <para> + <xref linkend="vboxmanage-startvm" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-sharedfolder.xml b/doc/manual/ru_RU/man_VBoxManage-sharedfolder.xml new file mode 100644 index 00000000..a3d4d88d --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-sharedfolder.xml @@ -0,0 +1,214 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage sharedfolder +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-sharedfolder" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage sharedfolder</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-sharedfolder</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-sharedfolder</refname> + <refpurpose>добавление или удаление общих папок</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-sharedfolder-add"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage sharedfolder add</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="req">--name=<replaceable>имя</replaceable></arg> + <arg choice="req">--hostpath=<replaceable>путь-в-хост-системе</replaceable></arg> + <arg>--readonly</arg> + <arg>--transient</arg> + <arg>--automount</arg> + <arg>--auto-mount-point=<replaceable>путь</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-sharedfolder-remove"> + <command>VBoxManage sharedfolder remove</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="req">--name=<replaceable>имя</replaceable></arg> + <arg>--transient</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Общие папки позволяют предоставить совместный доступ к данным + между хост-системой и гостевыми системами. Для использования + общих папок, сначала надо установить Дополнения Гостевой ОС + &product-name; в гостевой ОС. + </para> + <para> + Общая папка связана с именем разделяемого ресурса и полным + путем к папке или директории в хост-системе. Имя разделяемого + ресурса - это уникальное имя в пространстве имен ОС хоста. + </para> + <refsect2 id="vboxmanage-sharedfolder-add"> + <title>Добавить общую папку</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage sharedfolder add</command> создает + общую папку. Папка указывается в хост-системе. Когда папка + настроена, к содержимому папки в хост-системе может быть + предоставлен совместный доступ в гостевых ОС. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>имя-ВМ</replaceable></term> + <listitem><para> + Задает имя или UUID гостевой ВМ, которая разделяет папку + с хост-системой. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--name=<replaceable>имя</replaceable></term> + <listitem><para> + Задает имя разделяемого ресурса, который имеет + уникальное имя в пространстве имен ОС хоста. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--hostpath=<replaceable>путь-в-хост-системе</replaceable></term> + <listitem><para> + Задает абсолютный путь к папке или директории в ОС хоста + для предоставления доступа гостевым ОС. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--readonly</term> + <listitem><para> + Указывает, что разделяемый ресурс имеет доступ только + для чтения к файлам хоста. + </para><para> + По умолчанию, общие папки имеют доступ на чтение и на + запись к файлам хоста. Однако, в дистрибутивах Linux, + общие папки монтируются с файловыми разрешениями 770, + пользователем <literal>root</literal> и группой + <literal>vboxsf</literal>. Эта опция устанавливает + файловые разрешения в 700. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--transient</term> + <listitem><para> + Задает что разделяемый ресурс временный, что означает, что + он может быть добавлен и удален в время выполнения и не + сохраняется после выключения ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--automount</term> + <listitem><para> + Указывает, что разделяемый ресурс монтируется автоматически. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--auto-mount-point=<replaceable>путь</replaceable></term> + <listitem><para> + Задает точку монтирования разделяемого ресурса. Зависит от гостевой ОС. + </para><para> + Для гостевых систем Windows и OS/2 она должна быть неиспользуемой + буквой диска. Если оставить пустым (или указать используемую + букву диска), будет использована последняя неиспользуемая буква + диска вместо указанной (то есть ищется буква с <literal>Z:</literal> + по <literal>A:</literal>). + </para><para> + Для Linux, Solaris и других гостевых систем UNIX, он должен быть + абсолютным путем, например <filename>/mnt/mysharedfolder</filename>. + Если оставить пустым, расположение по умолчанию будет + <filename>/media/sf_<replaceable>имя-общей-папки</replaceable></filename>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-sharedfolder-remove"> + <title>Удалить общую папку</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage sharedfolder remove</command> + удаляет общую папку. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>имя-ВМ</replaceable></term> + <listitem><para> + Задает имя или UUID гостевой ВМ, которая разделяет папку + с хост-системой. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--name=<replaceable>имя</replaceable></term> + <listitem><para> + Задает имя удаляемого разделяемого ресурса. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--transient</term> + <listitem><para> + Указывает, что папка временная, что означает что она + может быть добавлена и удалена во время выполнения и не + сохраняется после выключения ВМ. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда создает общую папку, называемую + <filename>o7share</filename> для ВМ <filename>ol7</filename>. + Папка монтируется автоматически при старте ВМ. + </para> +<screen>$ VBoxManage sharedfolder add ol7 --name ol7share --hostpath "/home/user/ol7share" --automount</screen> + <para> + Следующая команда удаляет общую папку, называемую + <filename>o7share</filename> из ВМ <filename>ol7</filename>. + </para> +<screen>$ VBoxManage sharedfolder remove ol7 --name ol7share</screen> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-showmediuminfo.xml b/doc/manual/ru_RU/man_VBoxManage-showmediuminfo.xml new file mode 100644 index 00000000..57efa575 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-showmediuminfo.xml @@ -0,0 +1,142 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage showmediuminfo +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-showmediuminfo" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage showmediuminfo</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-showmediuminfo</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-showmediuminfo</refname> + <refpurpose>отображение информации о носителе</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-showmediuminfo"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage showmediuminfo</command> + <group> + <arg choice="plain">disk</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">floppy</arg> + </group> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-файла</replaceable></arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage showmediuminfo</command> показывает + следующую информацию о носителе: + </para> + <itemizedlist> + <listitem><para> + Размер + </para></listitem> + <listitem><para> + Размер на диске + </para></listitem> + <listitem><para> + Тип + </para></listitem> + <listitem><para> + Используется виртуальными машинами (ВМ) + </para></listitem> + </itemizedlist> + <para> + Носитель должен быть указан или через UUID, если носитель + зарегистрирован или через имя файла. Зарегистрированные носители + можно увидеть через <command>VBoxManage list hdds</command>, + <command>VBoxManage list dvds</command> или <command>VBoxManage list + floppies</command> соответственно. + </para> + <para> + Для обратной совместимости, можно также использовать команду + <command>showvdiinfo</command> для получения информации о + носителе. + </para> + <variablelist> + <varlistentry> + <term><literal>disk</literal> | <literal>dvd</literal> | <literal>floppy</literal></term> + <listitem><para> + Указывает тип носителя. Допустимые значения + <literal>disk</literal> (жесткий диск), + <literal>dvd</literal> или <literal>floppy</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>имя-файла</replaceable></term> + <listitem><para> + Задает Универсальный Уникальный Идентификатор (UUID) + или абсолютный путь к носителю или образу. + </para><para> + Если носитель зарегистрирован, можно указывать UUID. Можно + также просмотреть зарегистрированные образы через команды + <command>VBoxManage list hdds</command>, <command>VBoxManage + list dvds</command> или <command>VBoxManage list + floppies</command>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда показывает информацию об образе + диска <filename>disk01.vdi</filename>: + </para> +<screen>$ VBoxManage showmediuminfo disk01.vdi</screen> + <para> + Следующая команда показывает информацию об образе + флоппи диска <filename>floppy01.img</filename>. + </para> +<screen>$ VBoxManage showmediuminfo floppy floppy01.img</screen> + </refsect1> + + <refsect1> + <title>Смотрите также</title> + <para> + <xref linkend="vboxmanage-list" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-showvminfo.xml b/doc/manual/ru_RU/man_VBoxManage-showvminfo.xml new file mode 100644 index 00000000..ade50a1d --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-showvminfo.xml @@ -0,0 +1,186 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage showvminfo +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-showvminfo" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-18 00:40:56 +0100 (Wed, 18 Jan 2023) $</pubdate> + <title>VBoxManage showvminfo</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-showvminfo</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-showvminfo</refname> + <refpurpose>отображает информацию о конфигурации или содержимое файла журнала виртуальной машины</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-showvminfo-default"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage showvminfo</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg>--details</arg> + <arg>--machinereadable</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-showvminfo-log"> + <command>VBoxManage showvminfo</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="req">--log=<replaceable>индекс</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage showvminfo</command> выводит + информацию о конфигурации или содержимое файла журнала для + указанной виртуальной машины (ВМ). + </para> + <refsect2 id="vboxmanage-showvminfo-default"> + <title>Просмотр информации о виртуальной машине</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage showvminfo</command> выводит + информацию об указанной ВМ в подробном формате или в + машино-читаемом формате. + </para> + <para> + Команда <command>VBoxManage showvminfo</command> показывает + ту же самую информацию для указанной ВМ в том же формате, что + и команда <command>VBoxManage list vms --long</command>. + </para> + <variablelist> + <varlistentry> + <term><option>--details</option></term> + <listitem><para> + Включает подробную информацию о ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--machinereadable</option></term> + <listitem><para> + Указывает, что информация о ВМ должна быть в + машино-читаемом формате. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-showvminfo-log"> + <title>Просмотр содержимого журнала виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage showvminfo --log</command> выводит + содержимое одного из указанных файлов журналов ВМ. + </para> + <variablelist> + <varlistentry> + <term><option>--log=<replaceable>индекс</replaceable></option></term> + <listitem><para> + Задает численный индекс, идентифицирующий файл журнала. + </para><para> + Значение индекса начинается <literal>0</literal>, которая + указывает файл <filename>VBox.log</filename>. Значение + индекса <literal>1</literal> указывает файл + <filename>VBoxHardening.log</filename>. Значение индекса + начиная с <literal>2</literal> указывают другие файлы + журнала, такие как файл <filename>VBox.log.1</filename>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + Следующий пример показывает типичный вывод этой команды: + </para> +<screen>$ VBoxManage showvminfo "Windows 10" +VirtualBox Command Line Management Interface Version <replaceable>номер-версии</replaceable> +Copyright (C) 2005-2023 Oracle and/or its affiliates + +Имя: Windows 10 +Группы: / +Гостевая ОС: Windows 10 (64-bit) +UUID: 1bf3464d-57c6-4d49-92a9-a5cc3816b7e7 +Файл настроек: /home/username/VirtualBox VMs/Windows 10/Windows 10.vbox +Папка снимков: /home/username/VirtualBox VMs/Windows 10/Snapshots +Папка журнала: /home/username/VirtualBox VMs/Windows 10/Logs +UUID оборудования: 1bf3464d-57c6-4d49-92a9-a5cc3816b7e7 +Размер памяти: 2048MB +Page Fusion: off +Размер VRAM: 12MB +Время выполнения ЦПУ: 100% +...</screen> + <para> + Следующий пример показывает вывод информации в + машино-читаемом формате, которая отображает элементы + как строку + <replaceable>свойство</replaceable>=<replaceable>значение</replaceable>: + </para> +<screen>$ VBoxManage showvminfo "Windows 10" --machinereadable +... +groups="/" +ostype="Windows 10 (64-bit)" +UUID="1bf3464d-57c6-4d49-92a9-a5cc3816b7e7" +...</screen> + <para> + Следующий пример показывает содержимое файла + журнала <filename>VBox.log</filename>: + </para> +<screen>$ VBoxManage showvminfo "Windows 10" --log 0 +00:00:02.895106 VirtualBox VM 6.0.0_RC1 r127378 linux.amd64 (Dec 10 2018 17:16:06) release log +00:00:02.895109 Log opened 2018-12-14T14:31:44.088259000Z +00:00:02.895111 Build Type: release +00:00:02.895115 OS Product: Linux +00:00:02.895117 OS Release: 4.1.12-61.1.22.el7uek.x86_64 +00:00:02.895119 OS Version: #2 SMP Fri Dec 2 09:28:44 PST 2016 +...</screen> + </refsect1> + + <refsect1> + <title>Смотрите также</title> + <para> + <xref linkend="vboxmanage-list" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-signova.xml b/doc/manual/ru_RU/man_VBoxManage-signova.xml new file mode 100644 index 00000000..06aa389f --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-signova.xml @@ -0,0 +1,145 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage signova +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-signova" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage signova</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-signova</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-signova</refname> + <refpurpose>цифровая подпись OVA</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-signova"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage signova</command> + <arg choice="req"><replaceable>ova</replaceable></arg> + <arg choice="req">--certificate=<replaceable>файл</replaceable></arg> + <arg choice="req">--private-key=<replaceable>файл</replaceable></arg> + <group> + <arg choice="plain">--private-key-password-file=<replaceable>файл-с-паролем</replaceable></arg> + <arg choice="plain">--private-key-password=<replaceable>файл-с-паролем</replaceable></arg> + </group> + <arg>--digest-type=<replaceable>тип</replaceable></arg> + <group> + <arg choice="plain">--pkcs7</arg> + <arg choice="plain">--no-pkcs7</arg> + </group> + <arg>--intermediate-cert=<replaceable>файл</replaceable></arg> + <arg>--force</arg> + <arg>--verbose</arg> + <arg>--quiet</arg> + <arg>--dry-run</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage signova</command> добавляет цифровую + подпись к OVA файлу. + </para> + <!-- Add more description here --> + <variablelist> + <varlistentry> + <term><replaceable>ova</replaceable></term> + <listitem><para>подписываемый файл OVA.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--certificate=<replaceable>файл</replaceable></option></term> + <listitem><para> Файл, содержащий сертификат для подписи OVA. Он может + быть или в формате PEM (base64) или DER (бинарный). Команда определит, + какой из них.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--private-key=<replaceable>файл</replaceable></option></term> + <listitem><para>Файл, содержащий приватный ключ. Он может быть или в + формате PEM (base64) или DER (бинарный). Команда определит, + какой из них.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--private-key-password-file=<replaceable>файл-с-паролем</replaceable></option></term> + <listitem><para>Файл, содержащий пароль к приватному ключу.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--private-key-password=<replaceable>пароль</replaceable></option></term> + <listitem><para>Пароль к приватному ключу. <!-- add warning about visibility --> </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--digest-type=<replaceable>тип</replaceable></option></term> + <listitem> + <para>Выбирает алгоритм криптографического дайджеста, используемый + в подписи. Возможные значения: SHA-256 (по умолчанию), SHA-512 и SHA-1.</para> + <para>Некоторые старые версии OVFTool и другие продукты VMWare могут + требовать <option>--digest-type=sha-1</option> для принятия OVA.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--pkcs7</option>, <option>--no-pkcs7</option></term> + <listitem><para>Включает или отключает создание дополнительной подписи + PKCS#7/CMS. Включено по умолчанию.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--intermediate-cert=<replaceable>файл</replaceable></option></term> + <listitem><para>Файл содержащий промежуточный сертификат, который должен быть + включен в необязательную подпись PKCS#7/CMS. Как и другие, файл может быть + в форматах PEM или DER. Эта опция может повторяться для добавления нескольких + промежуточных сертификатов. Эта опция подразумевает опцию + <option>--pkcs7</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--force</option></term> + <listitem><para>Переписывает существующую сигнатуру если присутствует. Поведение + по умолчанию - завершиться неудачей если OVA уже подписан.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dry-run</option></term> + <listitem><para>Не изменять OVA на самом деле, просто протестировать операцию подписи.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>-v</option>, <option>--verbose</option>, <option>-q</option>, <option>--quiet</option></term> + <listitem><para>Управляет степенью подробности вывода при выполнении команды. Опцию + <option>--verbose</option> можно указывать несколько раз для получения более + подробного вывода. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> + diff --git a/doc/manual/ru_RU/man_VBoxManage-snapshot.xml b/doc/manual/ru_RU/man_VBoxManage-snapshot.xml new file mode 100644 index 00000000..dce74106 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-snapshot.xml @@ -0,0 +1,395 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage snapshot +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-snapshot" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage snapshot</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-snapshot</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-snapshot</refname> + <refpurpose>управляет снимками виртуальной машины &product-name;</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-snapshot"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-snapshot-take"> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + + <arg choice="plain">take</arg> + + <arg choice="req"><replaceable>имя-снимка</replaceable></arg> + + <arg>--description=<replaceable>описание</replaceable></arg> + + <arg>--live</arg> + + <arg>--uniquename Number,Timestamp,Space,Force</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-snapshot-delete"> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + + <arg choice="plain">delete</arg> + + <arg choice="req"><replaceable>имя-снимка</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-snapshot-restore"> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + + <arg choice="plain">restore</arg> + + <arg choice="req"><replaceable>имя-снимка</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-snapshot-restorecurrent"> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + + <arg choice="plain">restorecurrent</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-snapshot-edit"> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + + <arg choice="plain">edit</arg> + + <group choice="req"> + <arg choice="plain"><replaceable>имя-снимка</replaceable></arg> + <arg choice="plain">--current</arg> + </group> + + <arg>--description=<replaceable>описание</replaceable></arg> + + <arg>--name=<replaceable>новое-имя</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-snapshot-list"> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + + <arg choice="plain">list</arg> + + <group><arg>--details</arg><arg>--machinereadable</arg></group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-snapshot-showvminfo"> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + + <arg choice="plain">showvminfo</arg> + + <arg choice="req"><replaceable>имя-снимка</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage snapshot</command> управляет снимками. + </para> + <para> + &product-name; использует снимки для фиксации состояния виртуальной + машины (ВМ). Можно позднее использовать снимок для возврата к + состоянию, описываемому снимком. + </para> + <para> + Снимок - это полная копия настроек ВМ. Если снимок создается + во время работы ВМ, снимок также включает файл состояния ВМ. + </para> + <para> + После создания снимка, &product-name; создает + <emphasis>разностный жесткий диск</emphasis> для каждого обычного + диска связанного с хост-машиной. При восстановлении снимка, + &product-name; использует эти разностные файлы для быстрого + сброса содержимого виртуальных жестких дисков ВМ. + </para> + <para> + Для каждой команды <command>VBoxManage snapshot</command>, + необходимо указать имя или универсальный уникальный идентификатор + (UUID) ВМ для которого нужно сделать снимок. + </para> + <refsect2> + <title>Общие операнды команды</title> + <variablelist> + <varlistentry> + <term><replaceable>uuid|имя-ВМ</replaceable></term> + <listitem><para> + Задает UUID или имя ВМ. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-snapshot-take"> + <title>Сделать снимок виртуальной машины</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage snapshot take</command> делает + снимок текущего состояния ВМ. Необходимо указать имя снимка + и, необязательно, описание. Новый снимок вставляется в дерево + снимков как потомок текущего снимка и становится новым текущим + снимком. + </para> + <variablelist> + <varlistentry> + <term><option>--description=<replaceable>описание</replaceable></option></term> + <listitem><para> + Задает описание снимка. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--live</option></term> + <listitem><para> + Указывает, что ВМ не останавливается во время создания + снимка. Операция известна как живое создание снимка. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uniquename Number,Timestamp,Space,Force</option></term> + <listitem><para> + Будет описано позже. + </para><remark> + Что эта опция делает и как ее использовать? + </remark></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>имя-снимка</replaceable></term> + <listitem><para> + Задает имя создаваемого снимка. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-snapshot-delete"> + <title>Удалить снимок</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage snapshot delete</command> + удаляет указанный снимок. + </para> + <para> + Операция удаления может занять некоторое время из-за + того что разностные образы связанные со снимком могут быть + объединены с их дочерними разностными образами. + </para> + <variablelist> + <varlistentry> + <term><replaceable>имя-снимка</replaceable></term> + <listitem><para> + Задает UUID или имя снимка. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-snapshot-restore"> + <title>Восстановить снимок</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage snapshot restore</command> + восстанавливает указанный снимок. Эта операция сбрасывает + настройки и текущее состояние к указанному снимку. Состояние + ВМ, на котором восстанавливается снимок, теряется. По + завершении восстановления, указанный снимок становится новым + текущим снимком, а последующие снимки - дочерними к нему. + </para> + <variablelist> + <varlistentry> + <term><replaceable>имя-снимка</replaceable></term> + <listitem><para> + Задает UUID или имя снимка. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-snapshot-restorecurrent"> + <title>Восстановить текущий снимок</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage snapshot restorecurrent</command> + восстанавливает текущий снимок. Текущий снимок - это снимок, + от которого получено текущее состояние. Эта команда + эквивалентна команде <command>VBoxManage snapshot + restore</command> с указанием имени или UUID текущего снимка. + </para> + </refsect2> + <refsect2 id="vboxmanage-snapshot-edit"> + <title>Изменить имя или описание существующего снимка</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage snapshot edit</command> позволяет + изменить имя или описание указанного снимка. + </para> + <variablelist> + <varlistentry> + <term><replaceable>имя-снимка</replaceable></term> + <listitem><para> + Задает UUID или имя редактируемого снимка. + </para><para> + Эта опция взаимоисключающая с опцией + <option>--current</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--current</option></term> + <listitem><para> + Указывает, что нужно обновить текущую версию снимка. + </para><para> + Эта опция взаимоисключающая с указанием имени снимка + или его UUID. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--description=<replaceable>описание</replaceable></option></term> + <listitem><para> + Задает новое описание для указанного снимка. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--name=<replaceable>новое-имя</replaceable></option></term> + <listitem><para> + Задает новое имя снимка. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-snapshot-list"> + <title>Показать список снимков</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage snapshot list</command> показывает + все снимки ВМ. + </para> + <variablelist> + <varlistentry> + <term><option>--details</option></term> + <listitem><para> + Указывает, что вывод показывает подробную информацию о снимке. + </para><para> + Эта опция взаимоисключающая с опцией + <option>--machinereadable</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--machinereadable</option></term> + <listitem><para> + Указывает, что вывод производится в машино-читаемом + формате. + </para><para> + Эта опция взаимоисключающая с опцией + <option>--details</option>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-snapshot-showvminfo"> + <title>Показать информацию о настройках снимка</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage snapshot showvminfo</command> позволяет + просмотреть настройки ВМ, являющихся частью существующего снимка. + </para> + <variablelist> + <varlistentry> + <term><replaceable>имя-снимка</replaceable></term> + <listitem><para> + Задает UUID или имя снимка. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + Следующая команда создает снимок ВМ + <computeroutput>ol7u4</computeroutput>. Снимок называется + <computeroutput>ol7u4-snap-001</computeroutput>. Команда использует + опцию <option>--description</option> для передачи описания + содержимого снимка. + </para> +<screen> +$ VBoxManage snapshot ol7u4 take ol7u4-snap-001 \ +--description="Oracle Linux 7.4" +</screen> + <para> + Следующая команда показывает снимки ВМ + <computeroutput>ol7u4</computeroutput>. + </para> +<screen> +$ VBoxManage snapshot ol7u4 list +</screen> + <para> + Следующая команда изменяет описание снимка + <computeroutput>ol7u4-snap-001</computeroutput> ВМ + <computeroutput>ol7u4</computeroutput>. + </para> +<screen> +$ VBoxManage snapshot ol7u4 edit ol7u4-snap-001 \ +--description="Oracle Linux 7.4 with UEK4 kernel" +</screen> + <para> + Следующая команда показывает настройки ВМ снимка + <computeroutput>ol7u1-snap-001</computeroutput> ВМ + <computeroutput>ol7u4</computeroutput>. + </para> +<screen> +$ VBoxManage snapshot ol7u4 showvminfo ol7u4-snap-001 +Имя: ol7u4 +Группы: / +Гостевая ОС: Oracle (64-bit) +UUID: 43349d78-2ab3-4cb8-978f-0e755cd98090 +Файл настроек: C:\Users\user1\VirtualBox VMs\ol7u4\ol7u4.vbox +... +Снимки: + + Имя: ol7u4-snap-001 (UUID: 1cffc37d-5c37-4b86-b9c5-a0f157a55f43) + Описание: Oracle Linux 7.4 with UEK4 kernel +</screen> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-startvm.xml b/doc/manual/ru_RU/man_VBoxManage-startvm.xml new file mode 100644 index 00000000..2ade9374 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-startvm.xml @@ -0,0 +1,174 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage startvm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-startvm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage startvm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-startvm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-startvm</refname> + <refpurpose>запуск виртуальной машины</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-startvm"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage startvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg>--putenv=<replaceable>имя</replaceable>[=<replaceable>значение</replaceable>]</arg> + <arg>--type=<group> + <arg choice="plain">gui</arg> + <arg choice="plain">headless</arg> + <arg choice="plain">sdl</arg> + <arg choice="plain">separate</arg> + </group></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage startvm</command> запускает + виртуальную машину &product-name; (ВМ), которая в состоянии + "Выключено" или "Состояние сохранено". + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>имя-ВМ</replaceable></term> + <listitem><para> + Задает имя или Универсальный Уникальный Идентификатор + (UUID) ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--putenv=<replaceable>имя</replaceable>=<replaceable>значение</replaceable></option></term> + <listitem><para> + Назначает значение переменной окружения в виде пары + имя-значение. Например VBOX_DISABLE_HOST_DISK_CACHE=1. + </para><para> + Кратка форма этой опции <option>-E</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--type=gui | headless | sdl | separate</option></term> + <listitem><para> + Указывает фронтенд запускаемой ВМ. + </para><para> + Можно использовать команду <command>VBoxManage setproperty</command> + для установки фронтенда по умолчанию как глобального + значения. Альтернативно, можно использовать команду + <command>VBoxManage modifyvm</command> для указания + фронтенда по умолчанию для определенной ВМ. Если не + установлено значение по умолчанию ни глобально, ни + для указанной ВМ и не указана опция <option>--type</option>, + ВМ открывается в окне рабочего стола хоста. + </para><para> + Опция <option>--type</option> принимает следующие + значения: + </para><variablelist> + <varlistentry> + <term><literal>gui</literal></term> + <listitem><para> + Запускает ВМ в окне графического интерфейса + пользователя. Это значение по умолчанию. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>headless</literal></term> + <listitem><para> + Фоновый режим. Запускает ВМ только для + удаленного дисплея. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>sdl</literal></term> + <listitem><para> + Запускает ВМ, используя фронтенд VBoxSDL. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>separate</literal></term> + <listitem><para> + Запускает ВМ с отделяемым интерфейсом пользователя, + что означает что ВМ запущена в фоновом режиме с + интерфейсом пользователя в отдельном процессе. + </para><para> + Это экспериментальная функция, у которой отсутствует + некоторый функционал, например ускорение 3D. + </para></listitem> + </varlistentry> + </variablelist></listitem> + </varlistentry> + </variablelist> + <note> + <para> + Если ВМ не удается запуститься с определенным фронтендом и + информация об ошибке неубедительна, рассмотрите запуск ВМ + напрямую, путем запуска фронтенда. Этот обходной путь может + выдать дополнительную информацию об ошибке. + </para> + </note> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда запускает ВМ <literal>ol7u6</literal>: + </para> +<screen>$ VBoxManage startvm ol7u6</screen> + <para> + Следующая команда запускает ВМ <literal>ol7u6-mininstall</literal> + в фоновом режиме. + </para> +<screen>$ VBoxManage startvm ol7u6-mininstall --type headless</screen> + </refsect1> + + <refsect1> + <title>Смотрите также</title> + <para> +<!--<xref linkend="vboxmanage-vboxheadless" />--> + <xref linkend="vboxheadless" />, + <xref linkend="vboxmanage-setproperty" />, + <xref linkend="vboxmanage-modifyvm" />. + </para> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-storageattach.xml b/doc/manual/ru_RU/man_VBoxManage-storageattach.xml new file mode 100644 index 00000000..10a9444d --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-storageattach.xml @@ -0,0 +1,549 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage storageattach +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-storageattach" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage storageattach</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-storageattach</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-storageattach</refname> + <refpurpose>подключение, удаление и изменение носителей, используемых виртуальной машиной</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-storageattach"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage storageattach</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="req">--storagectl=<replaceable>имя</replaceable></arg> + <arg>--bandwidthgroup=<group choice="plain"> + <arg choice="plain">name</arg> + <arg choice="plain">none</arg> + </group></arg> + <arg>--comment=<replaceable>текст</replaceable></arg> + <arg>--device=<replaceable>номер</replaceable></arg> + <arg>--discard=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--encodedlun=<replaceable>lun</replaceable></arg> + <arg>--forceunmount</arg> + <arg>--hotpluggable=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--initiator=<replaceable>инициатор</replaceable></arg> + <arg>--intnet</arg> + <arg>--lun=<replaceable>lun</replaceable></arg> + <arg>--medium=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">emptydrive</arg> + <arg choice="plain">additions</arg> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-файла</replaceable></arg> + <arg choice="plain">host:<replaceable>диск</replaceable></arg> + <arg choice="plain">iscsi</arg> + </group></arg> + <arg>--mtype=<group choice="plain"> + <arg choice="plain">normal</arg> + <arg choice="plain">writethrough</arg> + <arg choice="plain">immutable</arg> + <arg choice="plain">shareable</arg> + <arg choice="plain">readonly</arg> + <arg choice="plain">multiattach</arg> + </group></arg> + <arg>--nonrotational=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--passthrough=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--passwordfile=<replaceable>файл</replaceable></arg> + <arg>--password=<replaceable>пароль</replaceable></arg> + <arg>--port=<replaceable>номер</replaceable></arg> + <arg>--server=<group choice="plain"> + <arg choice="plain"><replaceable>имя</replaceable></arg> + <arg choice="plain"><replaceable>ip</replaceable></arg> + </group></arg> + <arg>--setparentuuid=<replaceable>uuid</replaceable></arg> + <arg>--setuuid=<replaceable>uuid</replaceable></arg> + <arg>--target=<replaceable>цель</replaceable></arg> + <arg>--tempeject=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--tport=<replaceable>порт</replaceable></arg> + <arg>--type=<group choice="plain"> + <arg choice="plain">dvddrive</arg> + <arg choice="plain">fdd</arg> + <arg choice="plain">hdd</arg> + </group></arg> + <arg>--username=<replaceable>имя-пользователя</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage storageattach</command> позволяет + управлять носителями, подключенными к контроллеру через команду + <command>VBoxManage storagectl</command>. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>имя-ВМ</replaceable></term> + <listitem><para> + Задает Универсальный Уникальный Идентификатор (UUID) или + имя виртуальной машины (ВМ). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--storagectl=<replaceable>имя</replaceable></option></term> + <listitem><para> + Задает имя контроллера. Используйте команду + <command>VBoxManage showvminfo</command> для просмотра + подключенных к ВМ контроллеров. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--port=<replaceable>номер</replaceable></option></term> + <listitem><para> + Задает номер порта изменяемого контроллера. Необходимо + использовать эту опцию если у контроллера несколько портов. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--device=<replaceable>номер</replaceable></option></term> + <listitem><para> + Задает номер устройства изменяемого порта. Необходимо + использовать эту опцию если у контроллера несколько + устройств на порт. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--type=dvddrive | fdd | hdd</option></term> + <listitem><para> + Указывает тип диска, с которым связан носитель. + Опустить данный параметр можно только если тип носителя + может быть определен через опцию <option>--medium</option> + или через информацию, переданную более ранней командой + подключения носителя. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--medium=none | emptydrive | additions | <replaceable>uuid</replaceable> | <replaceable>имя-файла</replaceable> | host:<replaceable>диск</replaceable> | iscsi</option></term> + <listitem><para> + Задает одно из следующих значений: + </para><variablelist> + <varlistentry> + <term><literal>none</literal></term> + <listitem><para> + Удаляет любой существующее устройство из указанного слота. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>emptydrive</literal></term> + <listitem><para> + Только для виртуальных DVD или флоппи дисков. + </para><para> + Заставляет слот устройства вести себя как съемный + диск, в который не вставлен носитель. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>additions</literal></term> + <listitem><para> + Только для виртуальных DVD дисков. + </para><para> + Подключает образ Дополнений Гостевой ОС VirtualBox + в указанный слот устройств. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable></term> + <listitem><para> + Задает UUID носителя для подключения в указанный слот + устройства. Носитель должен быть уже известен + &product-name;, например носитель, подключенный к + другой ВМ. Используйте команду + <command>VBoxManage list</command> для просмотра + носителей. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>имя-файла</replaceable></term> + <listitem><para> + Задает полный путь к существующему образу диска + для подключения к указанному слоту устройства. + Образ диска может быть ISO, RAW, VDI, VMDK или + другого формата. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>host:<replaceable>диск</replaceable></literal></term> + <listitem><para> + Только для виртуальных DVD или флоппи дисков. + </para><para> + Соединяет указанный слот устройства к указанному + DVD или флоппи диску хост-компьютера. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>iscsi</literal></term> + <listitem><para> + Только для виртуальных жестких дисков. + </para><para> + Задает цель iSCSI, для которой необходимо указать + дополнительную информацию. Смотрите + <xref linkend="storage-iscsi" />. + </para></listitem> + </varlistentry> + </variablelist><para> + Для съемных дисков, таких как флоппи и DVD, можно менять + настройки во время выполнения ВМ. Изменения устройств или + слотов устройств жестких дисков требуют, чтобы ВМ была + выключена. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mtype=normal | writethrough | immutable | shareable | readonly | multiattach</option></term> + <listitem><para> + Указывает, как носитель ведет себя по отношению к снимкам + и операциям записи. Смотрите <xref linkend="hdimagewrites" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--comment=<replaceable>текст</replaceable></option></term> + <listitem><para> + Задает необязательное описание, сохраняемое с носителем. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--setuuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Изменяет UUID носителя перед подключением к ВМ. + </para><para> + Это экспертная опция. Неподходящие значения могут привести + к невозможности использовать носитель или к поломке + настроек ВМ если другая ВМ уже ссылается на такой же носитель. + </para><para> + Опция <option>--setuuid=""</option> назначает + новый случайный UUID образу, что может убрать ошибку + дублированного UUID, если была использована утилита + файлового копирования для дублирования образа. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--setparentuuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Изменяет родительский UUID носителя перед подключением к ВМ. + </para><para> + Это экспертная опция. Неподходящие значения могут привести + к невозможности использовать носитель или к поломке + настроек ВМ если другая ВМ уже ссылается на такой же носитель. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--passthrough=on | off</option></term> + <listitem><para> + Только для виртуальных DVD дисков. + </para><para> + Включает запись на DVD. Эта функция экспериментальная. + Смотрите <xref linkend="storage-cds" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tempeject=on | off</option></term> + <listitem><para> + Только для виртуальных DVD дисков. + </para><para> + Указывает, разрешать ли операцию временного извлечения + носителя по запросу гостевой системы. Если установлено + в <literal>on</literal>, носитель может быть извлечен. + Возможность операции извлечения по запросу гостевой + системы, не сохраняется, если ВМ выключена и + перезапущена. Таким образом, когда опция установлена + в <literal>on</literal> и ВМ перезапущена, первоначально + настроенный носитель все еще в дисководе. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nonrotational=on | off</option></term> + <listitem><para> + Позволяет указать, что виртуальный жесткий диск + не вращается. Некоторые гостевые ОС, например Windows 7 + и более поздние, считают такие диски твердотельными (SSD) + и не производят фрагментацию диска на них. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--discard=on | off</option></term> + <listitem><para> + Указывает, включать ли функцию автоудаления для виртуального + жесткого диска. Когда установлена в <literal>on</literal>, + образ VDI уменьшается в ответ на команду <command>trim</command> + гостевой ОС. + </para><para> + Виртуальный жесткий диск должен удовлетворять следующим + требованиям: + </para><itemizedlist> + <listitem><para> + Формат диска должен быть VDI. + </para></listitem> + <listitem><para> + Размер очищаемой области диска должен быть не менее 1 МБ. + </para></listitem> + <listitem><para> + Убедитесь, что обрезаемое пространство представляет + собой непрерывный блок размером не менее 1 МБ на + границе 1 МБ. + </para></listitem> + </itemizedlist><para> + Рассмотрите запуск команд дефрагментации в фоновом режиме + через cron для сохранения пространства. В Windows + запускайте команду <command>defrag.exe /D</command>. В + Linux запускайте команду <command>btrfs filesystem + defrag</command>. + </para><note> + <para> + При настройке гостевой ОС для выдачи команды + <command>trim</command>, гостевая ОС обычно рассматривает + диск как SSD. + </para> + <para> + Ext4 поддерживает опцию монтирования + <option>-o discard</option>. В Mac OS X может + потребоваться дополнительная настройка. Windows 7, 8 + и 10 автоматически определяет и поддерживает SSD. + Драйвер Linux <command>exFAT</command> от Samsung + поддерживает команду <command>trim</command>. + </para> + </note><para> + Реализация exFAT от Microsoft может не поддерживать эту + функцию. + </para><para> + Можно использовать другие способы для выдачи команд trim. + Команда Linux <command>fstrim</command> является частью + пакета <filename>util-linux</filename>. Ранние решения + требовали обнулить неиспользуемые области через команду + <command>zerofree</command> или подобную, затем уплотнить + диск. Можно производит данные шаги только при выключенной + ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bandwidthgroup=<replaceable>имя</replaceable></option></term> + <listitem><para> + Задает группу полосы пропускания, используемую в устройстве. + Смотрите <xref linkend="storage-bandwidth-limit" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--forceunmount</option></term> + <listitem><para> + Только для виртуальных DVD или флоппи дисков. + </para><para> + Принудительно размонтирует DVD, CD, или флоппи или + монтирует новый DVD, CD, или флоппи даже если предыдущий + съемный носитель заблокирован гостем на чтение. Смотрите + <xref linkend="storage-cds" />. + </para></listitem> + </varlistentry> + </variablelist> + <para> + Следующие опции применимы когда указана опция + <option>--medium=iscsi</option>: + </para> + <variablelist> + <varlistentry> + <term><option>--server=<replaceable>имя-хоста</replaceable> | <replaceable>IP-адрес</replaceable></option></term> + <listitem><para> + Задает имя хоста или IP адрес цели iSCSI. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--target=<replaceable>цель</replaceable></option></term> + <listitem><para> + Задает строку имени цели, определяемую целью + iSCSI и используется для идентификации ресурса хранилища. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tport=<replaceable>порт</replaceable></option></term> + <listitem><para> + Задает номер порта TCP/IP службы iSCSI цели. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--lun=<replaceable>LUN</replaceable></option></term> + <listitem><para> + Задает номер логической единицы ресурса цели. + Для единственного дисковода значение равно нулю. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--encodedlun=<replaceable>LUN</replaceable></option></term> + <listitem><para> + Задает LUN ресурса цели в виде закодированную в + шестнадцатеричном виде. Для единственного дисковода + значение равно нулю. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--username=<replaceable>имя-пользователя</replaceable></option></term> + <listitem><para> + Задает имя пользователя для аутентификации цели. + </para><note> + <para> + Если не установлен пароль на настройки, имя пользователя + сохраняется в виде простого текста в XML файле настроек + машины. + </para> + </note></listitem> + </varlistentry> + <varlistentry> + <term><option>--password=<replaceable>пароль</replaceable></option></term> + <listitem><para> + Задает пароль для аутентификации цели. + </para><note> + <para> + Если не установлен пароль на настройки, этот пароль + сохраняется в виде простого текста в XML файле + конфигурации машины. Когда пароль на настройки + установлен, пароль аутентификации цели сохраняется + в шифрованном виде. + </para> + </note><remark> + Этот дизайн не соответствует рекомендациям по безопасности + Oracle. У Вас не должно быть возможности указать пароль + в командной строке, так как пароль может быть увиден + в списке процессов. + </remark></listitem> + </varlistentry> + <varlistentry> + <term><option>--passwordfile=<replaceable>файл-с-паролем</replaceable></option></term> + <listitem><para> + Задает файл, содержащий пароль аутентификации цели + в виде простого текста. + </para><note> + <para> + Используйте настройки разрешений и владения, чтобы + убедиться, что содержимое этого файла не могут прочитать + неавторизованные пользователи. + </para> + </note></listitem> + </varlistentry> + <varlistentry> + <term><option>--initiator=<replaceable>инициатор</replaceable></option></term> + <listitem><para> + Задает инициатор iSCSI. + </para><para> + iSCSI инициатор от Microsoft - это система, например сервер, + которая подключается к IP сети и инициирует запросы и + получает ответы от iSCSI целей. SAN компоненты в + инициаторе iSCSI во многом аналогичны SAN компонентам Fibre + Channel и включают следующие: + </para><itemizedlist> + <listitem><para> + <emphasis role="bold">Драйвер iSCSI.</emphasis> + Траспортирует блоки команд iSCSI через сеть IP. Этот + драйвер iSCSI устанавливается в хост iSCSI и входит + в состав инициатор iSCSI от Microsoft. + </para></listitem> + <listitem><para> + <emphasis role="bold">Адаптер Gigabit Ethernet.</emphasis> + Подключается к цели iSCSI. Используйте адаптер + Ethernet, который может передавать 1000 мегабит в + секунду (Мб/с). Как и стандартные 10/100 адаптеры, + большинство гигабитных адаптеров используют + существующие кабели категории 5 или 6Е. Каждый порт + адаптера идентифицируется уникальным IP адресом. + </para></listitem> + <listitem><para> + <emphasis role="bold">Цель iSCSI.</emphasis> Это любое + устройство, которое получает команды iSCSI. Устройством + может быть как конечный узел, например устройство хранения, + так и промежуточное устройство, например сетевой мост + между устройствами IP и Fibre Channel. Каждый порт + контроллера массива хранилищ или сетевого моста + идентифицируется одним или несколькими IP адресами. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--intnet</option></term> + <listitem><para> + Указывает, подключаться ли к цели iSCSI, использующую + внутреннюю сеть. Эта настройка требует дальнейшую + настройку. Смотрите <xref linkend="iscsi-intnet" />. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда подключает образ диска <filename>o7.vdi</filename> + к указанному контроллеру SATA в ВМ <filename>ol7</filename>. + </para> +<screen>$ storageattach ol7 --storagectl "SATA Controller" --port 0 --device 0 \ +--type hdd --medium /VirtualBox/ol7/ol7.vdi</screen> + <para> + Следующая команда подключает образ DVD <filename>o7-r6-dvd.iso</filename> + к указанному контроллеру IDE в ВМ <filename>ol7</filename>. + </para> +<screen>$ VBoxManage storageattach ol7 --storagectl "IDE Controller" --port 0 --device 0 \ +--type dvddrive --medium ol7-r6-dvd.iso</screen> + </refsect1> + + <refsect1> + <title>Смотрите также</title> + <para> + <xref linkend="vboxmanage-list" />, + <xref linkend="vboxmanage-showvminfo" />, + <xref linkend="vboxmanage-storagectl" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-storagectl.xml b/doc/manual/ru_RU/man_VBoxManage-storagectl.xml new file mode 100644 index 00000000..25f39d75 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-storagectl.xml @@ -0,0 +1,203 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage storagectl +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-storagectl" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage storagectl</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-storagectl</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-storagectl</refname> + <refpurpose>управляет контроллером хранения</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <cmdsynopsis id="synopsis-vboxmanage-storagectl"> + <command>VBoxManage storagectl</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg choice="req">--name=<replaceable>имя-контроллера</replaceable></arg> + <arg>--add=<group choice="plain"> + <arg choice="plain">floppy</arg> + <arg choice="plain">ide</arg> + <arg choice="plain">pcie</arg> + <arg choice="plain">sas</arg> + <arg choice="plain">sata</arg> + <arg choice="plain">scsi</arg> + <arg choice="plain">usb</arg> + </group></arg> + <arg>--controller=<group choice="plain"> + <arg choice="plain">BusLogic</arg> + <arg choice="plain">I82078</arg> + <arg choice="plain">ICH6</arg> + <arg choice="plain">IntelAhci</arg> + <arg choice="plain">LSILogic</arg> + <arg choice="plain">LSILogicSAS</arg> + <arg choice="plain">NVMe</arg> + <arg choice="plain">PIIX3</arg> + <arg choice="plain">PIIX4</arg> + <arg choice="plain">USB</arg> + <arg choice="plain">VirtIO</arg> + </group></arg> + <arg>--bootable=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--hostiocache=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--portcount=<replaceable>количество</replaceable></arg> + <arg>--remove</arg> + <arg>--rename=<replaceable>новое-имя-контроллера</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage storagectl</command> позволяет + подключить, изменить или удалить контроллер хранилища. После + настройки контроллера, можно использовать команду + <command>VBoxManage storageattach</command> для подключения + виртуального носителя к контроллеру. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>имя-ВМ</replaceable></term> + <listitem><para> + Задает Универсальный Уникальный Идентификатор (UUID) или + имя виртуальной машины (ВМ). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--name=<replaceable>имя-контроллера</replaceable></option></term> + <listitem><para> + Задает имя контроллера хранения. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--add=<replaceable>тип-системной-шины</replaceable></option></term> + <listitem><para> + Задает тип системной шины, куда подключать контроллер + хранилища. Допустимые значения + <literal>floppy</literal>, <literal>ide</literal>, + <literal>pcie</literal>, <literal>sas</literal>, + <literal>sata</literal>, <literal>scsi</literal> и + <literal>usb</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--controller=<replaceable>тип-чипсета</replaceable></option></term> + <listitem><para> + Задает тип эмулируемого чипсета для указанного + контроллера хранилища. Допустимые значения + <literal>BusLogic</literal>, <literal>I82078</literal>, + <literal>ICH6</literal>, <literal>IntelAHCI</literal>, + <literal>LSILogic</literal>, <literal>LSILogicSAS</literal>, + <literal>NVMe</literal>, <literal>PIIX3</literal>, + <literal>PIIX4</literal> и <literal>USB</literal>. + </para><para> + Значение по умолчание изменяется, в соответствии с типом + контроллера хранилища. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--portcount=<replaceable>количество</replaceable></option></term> + <listitem><para> + Задает количество портов, поддерживаемых контроллером. + Допустимые значения зависят от контроллера. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--hostiocache=on|off</option></term> + <listitem><para> + Указывает, использовать ли I/O кэш хоста для всех образов + дисков, подключенных к контроллеру. Допустимые значения + <literal>on</literal> и <literal>off</literal>. Смотрите + <xref linkend="iocaching" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bootable=on|off</option></term> + <listitem><para> + Указывает, что контроллер загрузочный. Допустимые значения + <literal>on</literal> и <literal>off</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--rename=<replaceable>новое-имя-контроллера</replaceable></option></term> + <listitem><para> + Задает новое имя для контроллера хранилища. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--remove</option></term> + <listitem><para> + Удаляет контроллер хранилища из конфигурации ВМ. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда создает контроллер SATA, называемый + <literal>sata01</literal> и добавляет его в ВМ + <literal>ol7</literal>. Контроллер эмулирует чипсет IntelAHCI. + </para> +<screen>$ VBoxManage storagectl ol7 --name "sata01" --add sata --controller IntelAHCI</screen> + <para> + Следующая команда создает контроллер IDE называемый + <literal>ide01</literal> и добавляет его в ВМ <literal>ol7</literal> + VM. + </para> +<screen>$ VBoxManage storagectl ol7 --name "ide01" --add ide</screen> + </refsect1> + + <refsect1> + <title>Смотрите также</title> + <para> + <xref linkend="vboxmanage-storageattach" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-unattended.xml b/doc/manual/ru_RU/man_VBoxManage-unattended.xml new file mode 100644 index 00000000..40166cc6 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-unattended.xml @@ -0,0 +1,256 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage unattended +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-unattended" lang="en"> + + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage unattended</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-unattended</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-unattended</refname> + <refpurpose>unattended установка гостевой ОС</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-unattended-detect"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage unattended detect</command> + <arg choice="req">--iso=<replaceable>iso-установщика</replaceable></arg> + <arg>--machine-readable</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-unattended-install"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage unattended install</command> + <arg choice="req"><replaceable>uuid|имя-ВМ</replaceable></arg> + <arg choice="req">--iso=<replaceable>iso-инсталляции</replaceable></arg> + <arg>--user=<replaceable>логин</replaceable></arg> + <arg>--password=<replaceable>пароль</replaceable></arg> + <arg>--password-file=<replaceable>файл</replaceable></arg> + <arg>--full-user-name=<replaceable>имя</replaceable></arg> + <arg>--key=<replaceable>ключ-продукта</replaceable></arg> + <arg>--install-additions</arg> + <arg>--no-install-additions</arg> + <arg>--additions-iso=<replaceable>iso-дополнений</replaceable></arg> + <arg>--install-txs</arg> + <arg>--no-install-txs</arg> + <arg>--validation-kit-iso=<replaceable>iso-тестирования</replaceable></arg> + <arg>--locale=<replaceable>ll_CC</replaceable></arg> + <arg>--country=<replaceable>CC</replaceable></arg> + <arg>--time-zone=<replaceable>tz</replaceable></arg> + <arg>--hostname=<replaceable>имя-хоста</replaceable></arg> + <arg>--package-selection-adjustment=<replaceable>ключ</replaceable></arg> + <arg>--dry-run</arg> + <arg>--auxiliary-base-path=<replaceable>путь</replaceable></arg> + <arg>--image-index=<replaceable>номер</replaceable></arg> + <arg>--script-template=<replaceable>файл</replaceable></arg> + <arg>--post-install-template=<replaceable>файл</replaceable></arg> + <arg>--post-install-command=<replaceable>команда</replaceable></arg> + <arg>--extra-install-kernel-parameters=<replaceable>параметры</replaceable></arg> + <arg>--language=<replaceable>язык</replaceable></arg> + <arg>--start-vm=<replaceable>тип-сессии</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + + <refsect2 id="vboxmanage-unattended-detect"> + <title>unattended detect</title> + <remark role="help-copy-synopsis"/> + <para> + Определяет гостевую операционную систему (ОС) на указанном инсталляционном + ISO и отображает результат. Это может быть использовано как входные данные + при создании ВМ для устанавливаемого ISO. + </para> + <variablelist> + <varlistentry> + <term><option>--iso=<replaceable>iso-инсталляции</replaceable></option></term> + <listitem><para>Определяемый инсталляционный ISO.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--machine-readable</option></term> + <listitem><para>Производит вывод, который проще для разбора из скрипта.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-unattended-install"> + <title>unattended install</title> + <remark role="help-copy-synopsis"/> + <para> + Перенастраивает указанную ВМ для установки и опционально запуска ОС. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid|имя-ВМ</replaceable></term> + <listitem><para>Или UUID или имя (чувствительно к регистру) ВМ.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--iso=<replaceable>iso-инсталляции</replaceable></option></term> + <listitem><para>Инсталляционный ISO для запуска определения.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--user=<replaceable>логин</replaceable></option></term> + <listitem><para>Имя пользователя. (По умолчанию: vboxuser)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password=<replaceable>пароль</replaceable></option></term> + <listitem> + <para>Пароль пользователя. Он используется как для пользователя указанного через <option>--user</option>, так и для + пользователя root/administrator. (по умолчанию: changeme)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password-file=<replaceable>файл</replaceable></option></term> + <listitem> + <para>Альтернатива <option>--password</option> для передачи пароля. Специальное имя файла + <computeroutput>stdin</computeroutput> может использоваться для чтения пароля с стандартного потока ввода.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--full-user-name=<replaceable>имя</replaceable></option></term> + <listitem><para>Полное имя пользователя. (по умолчанию: --user)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--key=<replaceable>ключ-продукта</replaceable></option></term> + <listitem><para>Ключ продукта гостевой ОС. Не всем гостевым ОС требуется это.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--install-additions</option>, <option>--no-install-additions</option></term> + <listitem><para>Устанавливать ли Дополнения Гостевой ОС VirtualBox. (по умолчанию: --no-install-addations)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--additions-iso=<replaceable>iso-дополнений</replaceable></option></term> + <listitem> + <para>Путь к ISO Дополнений Гостевой ОС. (по умолчанию: installed/downloaded GAs)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--install-txs</option>, <option>--no-install-txs</option></term> + <listitem> + <para>Инсталлировать ли службу выполнения тестов (TXS) из VirtualBox ValidationKit. + Это полезно при подготовке ВМ к тестированию или подобной работы. (по умолчанию: --no-install-txs)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--validation-kit-iso=<replaceable>iso-тестирования</replaceable></option></term> + <listitem> + <para>Путь к VirtualBox ValidationKit ISO. Опция необходима если указана <option>--install-txs</option> + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--locale=<replaceable>ll_CC</replaceable></option></term> + <listitem> + <para>Спецификация базовая локали для гостевой системы, например en_US, de_CH, или nn_NO. (по умолчанию: host или en_US)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--country=<replaceable>CC</replaceable></option></term> + <listitem><para>Двухбуквенный кода страны если отличается от указанной в <option>--location</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--time-zone=<replaceable>tz</replaceable></option></term> + <listitem><para>Часовая зона для установки в гостевой ОС. (по умолчанию: часовая зона хоста или UTC)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--hostname=<replaceable>имя-хоста</replaceable></option></term> + <listitem> + <para> Полное доменное имя гостевой машины. (по умолчанию: <replaceable>имя-ВМ</replaceable>.myguest.virtualbox.org)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--package-selection-adjustment=<replaceable>ключ</replaceable></option></term> + <listitem> + <para> Корректировка выбора пакетов/компонентов гостевой ОС. Может быть указана более одного раза. В настоящее + время единственным распознаваемым ключевым словом является <computeroutput>minimal</computeroutput>, которое + запускает минимальную установку для некоторых гостевых ОС.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dry-run</option></term> + <listitem><para>Не создавать каких-либо файлов или делать изменения в конфигурации ВМ.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--start-vm=<replaceable>тип-сессии</replaceable></option></term> + <listitem> + <para>Запуск ВМ с помощью фронтенда, указанного в <replaceable>session-type</replaceable>. Это то же самое что + и опция <option>--type</option> для команды <computeroutput>startvm</computeroutput>, Но нам пришлось добавить + <computeroutput>none</computeroutput> для указания того, что ВМ не надо запускать. + (по умолчанию: <computeroutput>none</computeroutput>)</para></listitem> + </varlistentry> + </variablelist> + + <para>Дополнительные опции:</para> + <variablelist> + <varlistentry> + <term><option>--auxiliary-base-path=<replaceable>путь</replaceable></option></term> + <listitem> + <para>Префикс пути к файлам относящимся к носителю, созданные для установки. + (по умолчанию: <replaceable>папка-настроек-ВМ</replaceable>/Unattended-<replaceable>uuid-ВМ</replaceable>-)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--image-index=<replaceable>номер</replaceable></option></term> + <listitem><para>Индекс образа инсталляции Windows. (по умолчанию: 1)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--script-template=<replaceable>файл</replaceable></option></term> + <listitem><para>Шаблон скрипта unattended инсталляции. (по умолчанию: зависит от IMachine::OSTypeId)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--post-install-template=<replaceable>файл</replaceable></option></term> + <listitem><para>Шаблон скрипта после инсталляции. (по умолчанию: зависит от IMachine::OSTypeId)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--post-install-command=<replaceable>команда</replaceable></option></term> + <listitem> + <para>Единичная команда, запускаемая после завершения установки. Точный формат и точный момент, + когда будет запущена команда, зависит от установщика гостевой ОС.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--extra-install-kernel-parameters=<replaceable>параметры</replaceable></option></term> + <listitem> + <para> + Список дополнительных параметров ядра Linux в течение установки. (по умолчанию: зависит от IMachine::OSTypeId) + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--language=<replaceable>язык</replaceable></option></term> + <listitem> + <para> + Задает язык пользовательского интерфейса для Windows инсталляции. <replaceable>язык</replaceable> обычно + в виде {ll}-{CC}. Смотрите результаты detectedOSLanguages из <command>VBoxManage unattended detect</command>. + (по умолчанию: detectedOSLanguages[0])</para></listitem> + </varlistentry> + + </variablelist> + </refsect2> + + </refsect1> +</refentry> + diff --git a/doc/manual/ru_RU/man_VBoxManage-unregistervm.xml b/doc/manual/ru_RU/man_VBoxManage-unregistervm.xml new file mode 100644 index 00000000..e8e7ce06 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-unregistervm.xml @@ -0,0 +1,121 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage unregistervm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-unregistervm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage unregistervm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-unregistervm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-unregistervm</refname> + <refpurpose>отмена регистрации виртуальной машины</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-unregistervm"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage unregistervm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + </group> + <arg>--delete</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage unregistervm</command> отменяет + регистрацию виртуальной машины (ВМ). + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>имя-ВМ</replaceable></term> + <listitem><para> + Задает имя или Универсальный Уникальный Идентификатор (UUID) ВМ. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--delete</option></term> + <listitem><para> + Удаляет следующие файлы, относящиеся к ВМ автоматически: + </para><itemizedlist> + <listitem><para> + Все файл образов жестких дисков, включая разностные файлы. + </para></listitem> + <listitem><para> + Все файлы сохраненного состояния, созданные машиной, + включая файлы для каждого снимка. + </para></listitem> + <listitem><para> + XML файл определения ВМ и его резервные копии. + </para></listitem> + <listitem><para> + Файлы журналов ВМ. + </para></listitem> + <listitem><para> + Пустую директорию, связанную с незарегистрированной ВМ. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда отменяет регистрацию ВМ, называемую + <literal>vm2</literal>. + </para> +<screen>$ VBoxManage unregistervm vm2</screen> + <para> + Следующая команда отменяет регистрацию ВМ, называемую + <literal>vm3</literal>. Все файлы, относящиеся к ВМ удаляются. + </para> +<screen>$ VBoxManage unregistervm vm3 --delete +%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%</screen> + </refsect1> + + <refsect1> + <title>Смотри также</title> + <para> + <xref linkend="vboxmanage-registervm" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-updatecheck.xml b/doc/manual/ru_RU/man_VBoxManage-updatecheck.xml new file mode 100644 index 00000000..8339cc6c --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-updatecheck.xml @@ -0,0 +1,143 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage updatecheck +--> +<!-- + Copyright (C) 2020-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-updatecheck" lang="en"> + + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage updatecheck</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-updatecheck</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-updatecheck</refname> + <refpurpose>проверка на наличие новой версии VirtualBox</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-updatecheck-perform"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage updatecheck perform</command> + <arg>--machine-readable</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-updatecheck-list"> + <command>VBoxManage updatecheck list</command> + <arg>--machine-readable</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-updatecheck-modify"> + <command>VBoxManage updatecheck modify</command> + <group> + <arg choice="plain">--disable</arg> + <arg choice="plain">--enable</arg> + </group> + <arg>--channel=<replaceable>stable | withbetas | all</replaceable></arg> + <arg>--frequency=<replaceable>дни</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + + <para>Подкоманда <command>updatecheck</command> используется для проверки доступности новой версии + VirtualBox. Две опции подкоманды <command>updatecheck</command> используются для изменения + или просмотра настроек, относящихся к проверке новой версии VirtualBox.</para> + + <refsect2 id="vboxmanage-updatecheck-perform"> + <title>updatecheck perform</title> + <remark role="help-copy-synopsis"/> + <para> + Проверяет доступность новой версии VirtualBox. + </para> + <variablelist> + <varlistentry> + <term><option>--machine-readable</option></term><listitem><para>Машино-читаемый вывод.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-updatecheck-list"> + <title>updatecheck list</title> + <remark role="help-copy-synopsis"/> + <para> + Отображает текущие настройки, используемый при проверке новой версии VirtualBox. + </para> + <variablelist> + <varlistentry> + <term><option>--machine-readable</option></term><listitem><para>Машино-читаемый вывод.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-updatecheck-modify"> + <title>updatecheck modify</title> + <remark role="help-copy-synopsis"/> + <para> + Изменяет настройки, используемые при проверке новой версии VirtualBox. + </para> + <variablelist> + <varlistentry> + <term><option>--enable</option></term><listitem><para>Включает службу проверки обновлений.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--disable</option></term><listitem><para>Отключает службу проверки обновлений.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--channel=stable | withbetas | all</option></term> + <listitem><para>Предпочитаемый тип выпуска, используемый при определении доступности новой версии VirtualBox. По умолчанию 'stable'.</para> + <variablelist> + <varlistentry> + <term><option>stable</option></term> + <listitem><para>Проверяет на новые стабильные выпуски (корректирующие и минорные выпуски внутри того же самого мажорного выпуска) VirtualBox.</para> </listitem> + </varlistentry> + <varlistentry> + <term><option>all</option></term> + <listitem><para>Проверяет на новые стабильные выпуски (корректирующие и минорные выпуски внутри того же самого мажорного выпуска), а также мажорные выпуски VirtualBox.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>withbetas</option></term> + <listitem><para>Проверяет на новые стабильные выпуски (корректирующие и минорные выпуски внутри того же самого мажорного выпуска), мажорные и бета выпуски VirtualBox.</para></listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--frequency=дни</option></term> + <listitem><para>Указывает, как часто в днях проверять на новые версии VirtualBox.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsect1> + +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-usbdevsource.xml b/doc/manual/ru_RU/man_VBoxManage-usbdevsource.xml new file mode 100644 index 00000000..5d62a708 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-usbdevsource.xml @@ -0,0 +1,129 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage usbdevsource +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-usbdevsource" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage usbdevsource</title> + </refentryinfo> + + <refmeta> + <refentrytitle>vboxmanage-usbdevsource</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>vboxmanage-usbdevsource</refname> + <refpurpose>добавление и удаление источников USB устройств</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-usbdevsource-add"> + <command>VBoxManage usbdevsource add</command> + <arg choice="req"><replaceable>имя-источника</replaceable></arg> + <arg choice="req">--backend=<replaceable>бэкенд</replaceable></arg> + <arg choice="req">--address=<replaceable>адрес</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-usbdevsource-remove"> + <command>VBoxManage usbdevsource remove</command> + <arg choice="req"><replaceable>имя-источника</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage usbdevsource</command> добавляет + источник USB устройства и делает его доступным гостевым системам + в хосте. Можно также использовать эту команду для удаления + источника USB устройства. + </para> + <refsect2 id="vboxmanage-usbdevsource-add"> + <title>Добавить источник USB устройства</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage usbdevsource add</command> добавляет + источник USB устройства, и он становится доступен все гостевым + системам в хост-системе. + </para> + <variablelist> + <varlistentry> + <term><replaceable>имя-источника</replaceable></term> + <listitem><para> + Задает уникальное имя для источника USB устройства. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--address=<replaceable>адрес</replaceable></term> + <listitem><para> + Задает адрес USB бэкенда. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--backend=<replaceable>бэкенд</replaceable></term> + <listitem><para> + Задает используемый бэкенд службы USB прокси. + </para><remark> + Что такое служба USB прокси? Как определяется + используемый бэкенд? + </remark></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-usbdevsource-remove"> + <title>Удалить USB устройство</title> + <remark role="help-copy-synopsis"/> + <para> + Команда <command>VBoxManage usbdevsource remove</command> + удаляет USB устройство. + </para> + <variablelist> + <varlistentry> + <term><replaceable>имя-источника</replaceable></term> + <listitem><para> + Задает имя удаляемого источника USB устройства. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда добавляет сервер USB устройства называемый + <filename>hostusb01</filename>. + </para> +<screen>$ VBoxManage usbdevsource add hostusb01 --backend USBIP --address 10.0.1.16</screen> + </refsect1> +</refentry> diff --git a/doc/manual/ru_RU/man_VBoxManage-usbfilter.xml b/doc/manual/ru_RU/man_VBoxManage-usbfilter.xml new file mode 100644 index 00000000..e5e30510 --- /dev/null +++ b/doc/manual/ru_RU/man_VBoxManage-usbfilter.xml @@ -0,0 +1,322 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage usbfilter +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-usbfilter" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage usbfilter</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-usbfilter</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-usbfilter</refname> + <refpurpose>управление USB фильтрами</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <cmdsynopsis id="synopsis-vboxmanage-usbfilter-add"> + <command>VBoxManage usbfilter add</command> + <arg choice="req"><replaceable>индекс</replaceable>,0-<replaceable>N</replaceable></arg> + <arg choice="req">--target=<group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + <arg choice="plain">global</arg> + </group></arg> + <arg choice="req">--name=<replaceable>строка</replaceable></arg> + <arg choice="req">--action=ignore | hold</arg> + <arg>--active=yes | no</arg> + <arg>--vendorid=<replaceable>XXXX</replaceable></arg> + <arg>--productid=<replaceable>XXXX</replaceable></arg> + <arg>--revision=<replaceable>IIFF</replaceable></arg> + <arg>--manufacturer=<replaceable>строка</replaceable></arg> + <arg>--product=<replaceable>строка</replaceable></arg> + <arg>--port=<replaceable>hex</replaceable></arg> + <arg>--remote=yes | no</arg> + <arg>--serialnumber=<replaceable>строка</replaceable></arg> + <arg>--maskedinterfaces=<replaceable>XXXXXXXX</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-usbfilter-modify"> + <command>VBoxManage usbfilter modify</command> + <arg choice="req"><replaceable>индекс</replaceable>,0-<replaceable>N</replaceable></arg> + <arg choice="req">--target=<group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + <arg choice="plain">global</arg> + </group></arg> + <arg>--name=<replaceable>строка</replaceable></arg> + <arg>--action=ignore | hold</arg> + <arg>--active=yes | no</arg> + <arg>--vendorid=<replaceable>XXXX</replaceable> | ""</arg> + <arg>--productid=<replaceable>XXXX</replaceable> | ""</arg> + <arg>--revision=<replaceable>IIFF</replaceable> | ""</arg> + <arg>--manufacturer=<replaceable>строка</replaceable> | ""</arg> + <arg>--product=<replaceable>строка</replaceable> | ""</arg> + <arg>--port=<replaceable>hex</replaceable></arg> + <arg>--remote=yes | no</arg> + <arg>--serialnumber=<replaceable>строка</replaceable> | ""</arg> + <arg>--maskedinterfaces=<replaceable>XXXXXXXX</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-usbfilter-remove"> + <command>VBoxManage usbfilter remove</command> + <arg choice="req"><replaceable>индекс</replaceable>,0-<replaceable>N</replaceable></arg> + <arg choice="req">--target=<group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>имя-ВМ</replaceable></arg> + <arg choice="plain">global</arg> + </group></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Описание</title> + <para> + Команда <command>VBoxManage usbfilter</command> позволяет управлять + USB фильтрами для указанной виртуальной машиной (ВМ) или глобальными + USB фильтрами, влияющими на всю конфигурацию &product-name;. + </para> + <para> + Глобальные фильтры применяются перед фильтрами определенной ВМ. + Это означает, что можно использовать глобальный фильтр для + предотвращения захвата устройств какой-либо ВМ. + </para> + <para> + Глобальные фильтры применяются в определенном порядке. Применяется + только первый походящий данному устройству фильтр. Например, + первый глобальный фильтр делает доступным определенный + флеш-накопитель Kingston, тогда как второй фильтр игнорирует все + устройства Kingston. В результате применения этих фильтров, + определенный флеш-накопитель Kingston будет доступен любой машине, + имеющей соответствующий фильтр, но остальные устройства Kingston + доступны не будут. + </para> + <refsect2> + <title>Общие операнды и опции</title> + <variablelist> + <varlistentry> + <term>index,0-<replaceable>N</replaceable></term> + <listitem><para> + Задает единственное число, указывающее позицию фильтра + в списке. Ноль (<literal>0</literal>) представляет + первую позицию в списке. Если в данной позиции уже + существует фильтр, то этот фильтр, а также + следующие за ним передвигаются ниже по списку. + В противном случае, новый фильтр добавляется в + список. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--action=ignore | hold</option></term> + <listitem><para> + Указывает, разрешать ли доступ ВМ к устройствам, + подходящим к описанию фильтра (<literal>hold</literal>) + или запрещать (<literal>ignore</literal>). Эта опция + применяется только к глобальным фильтрам. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--active=yes | no</option></term> + <listitem><para> + Указывает, активен ли USB фильтр или временно отключен. + Допустимые значения <literal>yes</literal>, активирующая + фильтр и <literal>no</literal>, отключающая его. Значение + по умолчанию <literal>yes</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--manufacturer=<replaceable>строка</replaceable></option></term> + <listitem><para> + Задает фильтр по ID производителя как строку. Значение + по умолчанию пустое (<literal>""</literal>). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--maskedinterfaces=<replaceable>XXXXXXXX</replaceable></option></term> + <listitem><para> + Указывает фильтр маскированного интерфейса, который + используется для скрытия одного или нескольких USB + интерфейсов от гостевой системы. Значение - это битовая + маска, где набор битов соответствует скрываемому USB + интерфейсу или снятие маски. Эта функция поддерживается + только только в хост-системах Linux. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--name=<replaceable>имя-фильтра</replaceable></option></term> + <listitem><para> + Задает имя фильтра. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--port=<replaceable>hex</replaceable></option></term> + <listitem><para> + Задает фильтр по номеру USB порта (hub port number). Значение по + умолчанию - пустая строка (<literal>""</literal>). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--product=<replaceable>строка</replaceable></option></term> + <listitem><para> + Задает фильтр по ID продукта как строку. Значение по + умолчанию пустое (<literal>""</literal>). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--productid=<replaceable>XXXX</replaceable></option></term> + <listitem><para> + Задает фильтр по ID продукта. Строковое представление + для точного соответствия имеет вид + <replaceable>XXXX</replaceable>, где + <replaceable>X</replaceable> - это шестнадцатеричная + цифра включающая лидирующие нули. Значение по умолчанию + пустое (<literal>""</literal>). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--remote=yes | no</option></term> + <listitem><para> + Задает удаленный фильтр, показывающий подключено ли + физически устройство к удаленному клиенту VRDE или + или к локальной системе. Эта опцию применяется только + к фильтрам ВМ. Значение по умолчанию пустое + (<literal>""</literal>). + </para><remark> + Почему значение по умолчанию пустое когда допустимые + значения <literal>yes</literal> или <literal>no</literal>? + </remark></listitem> + </varlistentry> + <varlistentry> + <term><option>--revision=<replaceable>IIFF</replaceable></option></term> + <listitem><para> + Задает фильтр по ID ревизии. Строковое представление + для точного соответствия имеет вид <replaceable>IIFF</replaceable>. + <replaceable>I</replaceable> - это десятичная цифра + целой части ревизии. <replaceable>F</replaceable> - + это десятичная цифра ее дробной части включающая + лидирующие и замыкающие нули. Значение по умолчанию + пустое (<literal>""</literal>). + </para><para> + Для того, чтобы указать диапазон ревизий ID, убедитесь + что используется шестнадцатеричная форма, то есть в виде + 16 битного упакованного двоично-десятичного значения. + Например, выражение <literal>int:0x0100-0x0199</literal> + соответствует любой ревизии с 1.0 по 1.99 включительно. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--serialnumber=<replaceable>строка</replaceable></option></term> + <listitem><para> + Задает фильтр серийного номера как строку. Значение по + умолчанию пустое(<literal>""</literal>). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--target=<replaceable>uuid</replaceable> | <replaceable>имя-ВМ</replaceable> | global</option></term> + <listitem><para> + Указывает ВМ, к которой подключается фильтр. Можно + указать Универсальный Уникальный Идентификатор (UUID) + или имя ВМ. Для применения описания фильтра ко всем ВМ, + укажите <literal>global</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vendorid=<replaceable>XXXX</replaceable></option></term> + <listitem><para> + Задает фильтр по ID поставщика, который представляется + строкой шестнадцатеричного номера, состоящего из + четырех цифр включая лидирующие нули. Значение по + умолчанию пустое (<literal>""</literal>). + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-usbfilter-add"> + <title>Добавить USB фильтр или глобальный фильтр</title> + <remark role="help-copy-synopsis"/> + <para> + Используйте команду <command>VBoxManage usbfilter add</command> + для создания нового USB фильтра. + </para> + <para> + Дополнительно укажите параметры для фильтрации. Можно использовать + команду <command>VBoxManage list usbhost</command> для просмотра + параметров устройств, подключенных к вашей системе. + </para> + </refsect2> + <refsect2 id="vboxmanage-usbfilter-modify"> + <title>Изменить USB фильтр или глобальный фильтр</title> + <remark role="help-copy-synopsis"/> + <para> + Используйте команду <command>VBoxManage usbfilter modify</command> + для изменения USB фильтра. Можно использовать команду + <command>VBoxManage list usbfilters</command> для отображения + индексов глобальных фильтров и команду + <command>VBoxManage showvminfo</command> для отображения + индексов по определенной машине. + </para> + </refsect2> + <refsect2 id="vboxmanage-usbfilter-remove"> + <title>Удалить USB фильтр или глобальный фильтр</title> + <remark role="help-copy-synopsis"/> + <para> + Используйте команду <command>VBoxManage usbfilter remove</command> + для удаления USB фильтра. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Примеры</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + Следующая команда отображает доступные USB устройства в хост-системе. + </para> +<screen>$ VBoxManage list usbhost</screen> + <para> + Следующая команда добавляет USB фильтр, называемый + <filename>filter01</filename> к ВМ <filename>ol7</filename>. + Фильтр определяет флеш-накопитель Kingston DataTraveler и + помещается первым в списке USB фильтров ВМ. + </para> +<screen>$ VBoxManage usbfilter add 0 --target ol7 --name filter01 --vendorid 0x0930 --productid 0x6545</screen> + <para> + Следующая команда удаляет USB фильтр, который второй в списке + ВМ <filename>ol7</filename> VM. + </para> +<screen>$ VBoxManage usbfilter remove 1 --target ol7</screen> + </refsect1> +</refentry> diff --git a/doc/manual/string.xsl b/doc/manual/string.xsl new file mode 100644 index 00000000..e6ea7595 --- /dev/null +++ b/doc/manual/string.xsl @@ -0,0 +1,1237 @@ +<?xml version="1.0"?> + +<!-- This file is taken from the XSLT Standard Library as available + from http://xsltsl.sourceforge.net/. Except for this notice, it + has not been modified. --> + +<xsl:stylesheet version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:doc="http://xsltsl.org/xsl/documentation/1.0" + xmlns:str="http://xsltsl.org/string" + extension-element-prefixes="doc str"> + + <doc:reference xmlns=""> + <referenceinfo> + <releaseinfo role="meta"> + $Id: string.xsl $ + </releaseinfo> + <author> + <surname>Ball</surname> + <firstname>Steve</firstname> + </author> + <copyright> + <year>2002</year> + <year>2001</year> + <holder>Steve Ball</holder> + </copyright> + </referenceinfo> + + <title>String Processing</title> + + <partintro> + <section> + <title>Introduction</title> + + <para>This module provides templates for manipulating strings.</para> + + </section> + </partintro> + + </doc:reference> + + <!-- Common string constants and datasets as XSL variables --> + + <!-- str:lower and str:upper contain pairs of lower and upper case + characters. Below insanely long strings should contain the + official lower/uppercase pairs, making this stylesheet working + for every language on earth. Hopefully. --> + <!-- These values are not enough, however. There are some + exceptions, dealt with below. --> + <xsl:variable name="xsltsl-str-lower" select="'abcdefghijklmnopqrstuvwxyzµàáâãäåæçèéêëìíîïðñòóôõöøùúûüýþÿāăąćĉċčďđēĕėęěĝğġģĥħĩīĭįıijĵķĺļľŀłńņňŋōŏőœŕŗřśŝşšţťŧũūŭůűųŵŷźżžſƃƅƈƌƒƕƙơƣƥƨƭưƴƶƹƽƿDždžLjljNjnjǎǐǒǔǖǘǚǜǝǟǡǣǥǧǩǫǭǯDzdzǵǹǻǽǿȁȃȅȇȉȋȍȏȑȓȕȗșțȝȟȣȥȧȩȫȭȯȱȳɓɔɖɗəɛɠɣɨɩɯɲɵʀʃʈʊʋʒͅάέήίαβγδεζηθικλμνξοπρςστυφχψωϊϋόύώϐϑϕϖϛϝϟϡϣϥϧϩϫϭϯϰϱϲϵабвгдежзийклмнопрстуфхцчшщъыьэюяѐёђѓєѕіїјљњћќѝўџѡѣѥѧѩѫѭѯѱѳѵѷѹѻѽѿҁҍҏґғҕҗҙқҝҟҡңҥҧҩҫҭүұҳҵҷҹһҽҿӂӄӈӌӑӓӕӗәӛӝӟӡӣӥӧөӫӭӯӱӳӵӹաբգդեզէըթժիլխծկհձղճմյնշոչպջռսվտրցւփքօֆḁḃḅḇḉḋḍḏḑḓḕḗḙḛḝḟḡḣḥḧḩḫḭḯḱḳḵḷḹḻḽḿṁṃṅṇṉṋṍṏṑṓṕṗṙṛṝṟṡṣṥṧṩṫṭṯṱṳṵṷṹṻṽṿẁẃẅẇẉẋẍẏẑẓẕẛạảấầẩẫậắằẳẵặẹẻẽếềểễệỉịọỏốồổỗộớờởỡợụủứừửữựỳỵỷỹἀἁἂἃἄἅἆἇἐἑἒἓἔἕἠἡἢἣἤἥἦἧἰἱἲἳἴἵἶἷὀὁὂὃὄὅὑὓὕὗὠὡὢὣὤὥὦὧὰάὲέὴήὶίὸόὺύὼώᾀᾁᾂᾃᾄᾅᾆᾇᾐᾑᾒᾓᾔᾕᾖᾗᾠᾡᾢᾣᾤᾥᾦᾧᾰᾱᾳιῃῐῑῠῡῥῳⅰⅱⅲⅳⅴⅵⅶⅷⅸⅹⅺⅻⅼⅽⅾⅿⓐⓑⓒⓓⓔⓕⓖⓗⓘⓙⓚⓛⓜⓝⓞⓟⓠⓡⓢⓣⓤⓥⓦⓧⓨⓩａｂｃｄｅｆｇｈｉｊｋｌｍｎｏｐｑｒｓｔｕｖｗｘｙｚ𐐨𐐩𐐪𐐫𐐬𐐭𐐮𐐯𐐰𐐱𐐲𐐳𐐴𐐵𐐶𐐷𐐸𐐹𐐺𐐻𐐼𐐽𐐾𐐿𐑀𐑁𐑂𐑃𐑄𐑅𐑆𐑇𐑈𐑉𐑊𐑋𐑌𐑍'"/> + <xsl:variable name="xsltsl-str-upper" select="'ABCDEFGHIJKLMNOPQRSTUVWXYZΜÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞŸĀĂĄĆĈĊČĎĐĒĔĖĘĚĜĞĠĢĤĦĨĪĬĮIIJĴĶĹĻĽĿŁŃŅŇŊŌŎŐŒŔŖŘŚŜŞŠŢŤŦŨŪŬŮŰŲŴŶŹŻŽSƂƄƇƋƑǶƘƠƢƤƧƬƯƳƵƸƼǷDŽDŽLJLJNJNJǍǏǑǓǕǗǙǛƎǞǠǢǤǦǨǪǬǮDZDZǴǸǺǼǾȀȂȄȆȈȊȌȎȐȒȔȖȘȚȜȞȢȤȦȨȪȬȮȰȲƁƆƉƊƏƐƓƔƗƖƜƝƟƦƩƮƱƲƷΙΆΈΉΊΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΣΤΥΦΧΨΩΪΫΌΎΏΒΘΦΠϚϜϞϠϢϤϦϨϪϬϮΚΡΣΕАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЪЫЬЭЮЯЀЁЂЃЄЅІЇЈЉЊЋЌЍЎЏѠѢѤѦѨѪѬѮѰѲѴѶѸѺѼѾҀҌҎҐҒҔҖҘҚҜҞҠҢҤҦҨҪҬҮҰҲҴҶҸҺҼҾӁӃӇӋӐӒӔӖӘӚӜӞӠӢӤӦӨӪӬӮӰӲӴӸԱԲԳԴԵԶԷԸԹԺԻԼԽԾԿՀՁՂՃՄՅՆՇՈՉՊՋՌՍՎՏՐՑՒՓՔՕՖḀḂḄḆḈḊḌḎḐḒḔḖḘḚḜḞḠḢḤḦḨḪḬḮḰḲḴḶḸḺḼḾṀṂṄṆṈṊṌṎṐṒṔṖṘṚṜṞṠṢṤṦṨṪṬṮṰṲṴṶṸṺṼṾẀẂẄẆẈẊẌẎẐẒẔṠẠẢẤẦẨẪẬẮẰẲẴẶẸẺẼẾỀỂỄỆỈỊỌỎỐỒỔỖỘỚỜỞỠỢỤỦỨỪỬỮỰỲỴỶỸἈἉἊἋἌἍἎἏἘἙἚἛἜἝἨἩἪἫἬἭἮἯἸἹἺἻἼἽἾἿὈὉὊὋὌὍὙὛὝὟὨὩὪὫὬὭὮὯᾺΆῈΈῊΉῚΊῸΌῪΎῺΏᾈᾉᾊᾋᾌᾍᾎᾏᾘᾙᾚᾛᾜᾝᾞᾟᾨᾩᾪᾫᾬᾭᾮᾯᾸᾹᾼΙῌῘῙῨῩῬῼⅠⅡⅢⅣⅤⅥⅦⅧⅨⅩⅪⅫⅬⅭⅮⅯⒶⒷⒸⒹⒺⒻⒼⒽⒾⒿⓀⓁⓂⓃⓄⓅⓆⓇⓈⓉⓊⓋⓌⓍⓎⓏＡＢＣＤＥＦＧＨＩＪＫＬＭＮＯＰＱＲＳＴＵＶＷＸＹＺ𐐀𐐁𐐂𐐃𐐄𐐅𐐆𐐇𐐈𐐉𐐊𐐋𐐌𐐍𐐎𐐏𐐐𐐑𐐒𐐓𐐔𐐕𐐖𐐗𐐘𐐙𐐚𐐛𐐜𐐝𐐞𐐟𐐠𐐡𐐢𐐣𐐤𐐥'"/> + <xsl:variable name="xsltsl-str-digits" select="'0123456789'"/> + <!-- space (#x20) characters, carriage returns, line feeds, or tabs. --> + <xsl:variable name="xsltsl-str-ws" select="' 	
'"/> + + <doc:template name="str:to-upper" xmlns=""> + <refpurpose>Make string uppercase</refpurpose> + + <refdescription> + <para>Converts all lowercase letters to uppercase.</para> + </refdescription> + + <refparameter> + <variablelist> + <varlistentry> + <term>text</term> + <listitem> + <para>The string to be converted</para> + </listitem> + </varlistentry> + </variablelist> + </refparameter> + + <refreturn> + <para>Returns string with all uppercase letters.</para> + </refreturn> + </doc:template> + + <xsl:template name="str:to-upper"> + <xsl:param name="text"/> + + <!-- Below exception is extracted from unicode's SpecialCasing.txt + file. It's the german lowercase "eszett" (the thing looking + like a greek beta) that's to become "SS" in uppercase (note: + that are *two* characters, that's why it doesn't fit in the + list of upper/lowercase characters). There are more + characters in that file (103, excluding the locale-specific + ones), but they seemed to be much less used to me and they + add up to a hellish long stylesheet.... - Reinout --> + <xsl:param name="modified-text"> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text"> + <xsl:value-of select="$text"/> + </xsl:with-param> + <xsl:with-param name="replace"> + <xsl:text>ß</xsl:text> + </xsl:with-param> + <xsl:with-param name="with"> + <xsl:text>S</xsl:text> + <xsl:text>S</xsl:text> + </xsl:with-param> + </xsl:call-template> + </xsl:param> + + <xsl:value-of select="translate($modified-text, $xsltsl-str-lower, $xsltsl-str-upper)"/> + </xsl:template> + + <doc:template name="str:to-lower" xmlns=""> + <refpurpose>Make string lowercase</refpurpose> + + <refdescription> + <para>Converts all uppercase letters to lowercase.</para> + </refdescription> + + <refparameter> + <variablelist> + <varlistentry> + <term>text</term> + <listitem> + <para>The string to be converted</para> + </listitem> + </varlistentry> + </variablelist> + </refparameter> + + <refreturn> + <para>Returns string with all lowercase letters.</para> + </refreturn> + </doc:template> + + <xsl:template name="str:to-lower"> + <xsl:param name="text"/> + + <xsl:value-of select="translate($text, $xsltsl-str-upper, $xsltsl-str-lower)"/> + </xsl:template> + + <doc:template name="str:capitalise" xmlns=""> + <refpurpose>Capitalise string</refpurpose> + + <refdescription> + <para>Converts first character of string to an uppercase letter. All remaining characters are converted to lowercase.</para> + </refdescription> + + <refparameter> + <variablelist> + <varlistentry> + <term>text</term> + <listitem> + <para>The string to be capitalised</para> + </listitem> + </varlistentry> + <varlistentry> + <term>all</term> + <listitem> + <para>Boolean controlling whether all words in the string are capitalised.</para> + <para>Default is true.</para> + </listitem> + </varlistentry> + </variablelist> + </refparameter> + + <refreturn> + <para>Returns string with first character uppcase and all remaining characters lowercase.</para> + </refreturn> + </doc:template> + + <xsl:template name="str:capitalise"> + <xsl:param name="text"/> + <xsl:param name="all" select="true()"/> + + <xsl:choose> + <xsl:when test="$all and (contains($text, ' ') or contains($text, ' ') or contains($text, ' '))"> + <xsl:variable name="firstword"> + <xsl:call-template name="str:substring-before-first"> + <xsl:with-param name="text" select="$text"/> + <xsl:with-param name="chars" select="$xsltsl-str-ws"/> + </xsl:call-template> + </xsl:variable> + <xsl:call-template name="str:capitalise"> + <xsl:with-param name="text"> + <xsl:value-of select="$firstword"/> + </xsl:with-param> + <xsl:with-param name="all" select="false()"/> + </xsl:call-template> + <xsl:value-of select="substring($text, string-length($firstword) + 1, 1)"/> + <xsl:call-template name="str:capitalise"> + <xsl:with-param name="text"> + <xsl:value-of select="substring($text, string-length($firstword) + 2)"/> + </xsl:with-param> + </xsl:call-template> + </xsl:when> + + <xsl:otherwise> + <xsl:call-template name="str:to-upper"> + <xsl:with-param name="text" select="substring($text, 1, 1)"/> + </xsl:call-template> + <xsl:call-template name="str:to-lower"> + <xsl:with-param name="text" select="substring($text, 2)"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <doc:template name="str:to-camelcase" xmlns=""> + <refpurpose>Convert a string to one camelcase word</refpurpose> + + <refdescription> + <para>Converts a string to one lowerCamelCase or UpperCamelCase + word, depending on the setting of the "upper" + parameter. UpperCamelCase is also called MixedCase while + lowerCamelCase is also called just camelCase. The template + removes any spaces, tabs and slashes, but doesn't deal with + other punctuation. It's purpose is to convert strings like + "hollow timber flush door" to a term suitable as identifier or + XML tag like "HollowTimberFlushDoor". + </para> + </refdescription> + + <refparameter> + <variablelist> + <varlistentry> + <term>text</term> + <listitem> + <para>The string to be capitalised</para> + </listitem> + </varlistentry> + <varlistentry> + <term>upper</term> + <listitem> + <para>Boolean controlling whether the string becomes an + UpperCamelCase word or a lowerCamelCase word.</para> + <para>Default is true.</para> + </listitem> + </varlistentry> + </variablelist> + </refparameter> + + <refreturn> + <para>Returns string with first character uppcase and all remaining characters lowercase.</para> + </refreturn> + </doc:template> + + <xsl:template name="str:to-camelcase"> + <xsl:param name="text"/> + <xsl:param name="upper" select="true()"/> + <!-- First change all 'strange' characters to spaces --> + <xsl:param name="string-with-only-spaces"> + <xsl:value-of select="translate($text,concat($xsltsl-str-ws,'/'),' ')"/> + </xsl:param> + <!-- Then process them --> + <xsl:param name="before-space-removal"> + <xsl:variable name="firstword"> + <xsl:call-template name="str:substring-before-first"> + <xsl:with-param name="text" select="$string-with-only-spaces"/> + <xsl:with-param name="chars" select="$xsltsl-str-ws"/> + </xsl:call-template> + </xsl:variable> + <xsl:choose> + <xsl:when test="$upper"> + <xsl:call-template name="str:to-upper"> + <xsl:with-param name="text" select="substring($firstword, 1, 1)"/> + </xsl:call-template> + <xsl:call-template name="str:to-lower"> + <xsl:with-param name="text" select="substring($firstword, 2)"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name="str:to-lower"> + <xsl:with-param name="text" select="$firstword"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> + + <xsl:call-template name="str:capitalise"> + <xsl:with-param name="text"> + <xsl:value-of select="substring($string-with-only-spaces, string-length($firstword) + 2)"/> + </xsl:with-param> + <xsl:with-param name="all" select="true()"/> + </xsl:call-template> + </xsl:param> + <xsl:value-of select="translate($before-space-removal,' ','')"/> + </xsl:template> + + <doc:template name="str:substring-before-first" xmlns=""> + <refpurpose>String extraction</refpurpose> + + <refdescription> + <para>Extracts the portion of string 'text' which occurs before any of the characters in string 'chars'.</para> + </refdescription> + + <refparameter> + <variablelist> + <varlistentry> + <term>text</term> + <listitem> + <para>The string from which to extract a substring.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>chars</term> + <listitem> + <para>The string containing characters to find.</para> + </listitem> + </varlistentry> + </variablelist> + </refparameter> + + <refreturn> + <para>Returns string.</para> + </refreturn> + </doc:template> + + <xsl:template name="str:substring-before-first"> + <xsl:param name="text"/> + <xsl:param name="chars"/> + + <xsl:choose> + + <xsl:when test="string-length($text) = 0"/> + + <xsl:when test="string-length($chars) = 0"> + <xsl:value-of select="$text"/> + </xsl:when> + + <xsl:when test="contains($text, substring($chars, 1, 1))"> + <xsl:variable name="this" select="substring-before($text, substring($chars, 1, 1))"/> + <xsl:variable name="rest"> + <xsl:call-template name="str:substring-before-first"> + <xsl:with-param name="text" select="$text"/> + <xsl:with-param name="chars" select="substring($chars, 2)"/> + </xsl:call-template> + </xsl:variable> + + <xsl:choose> + <xsl:when test="string-length($this) < string-length($rest)"> + <xsl:value-of select="$this"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$rest"/> + </xsl:otherwise> + </xsl:choose> + </xsl:when> + + <xsl:otherwise> + <xsl:call-template name="str:substring-before-first"> + <xsl:with-param name="text" select="$text"/> + <xsl:with-param name="chars" select="substring($chars, 2)"/> + </xsl:call-template> + </xsl:otherwise> + + </xsl:choose> + </xsl:template> + + <doc:template name="str:substring-after-last" xmlns=""> + <refpurpose>String extraction</refpurpose> + + <refdescription> + <para>Extracts the portion of string 'text' which occurs after the last of the character in string 'chars'.</para> + </refdescription> + + <refparameter> + <variablelist> + <varlistentry> + <term>text</term> + <listitem> + <para>The string from which to extract a substring.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>chars</term> + <listitem> + <para>The string containing characters to find.</para> + </listitem> + </varlistentry> + </variablelist> + </refparameter> + + <refreturn> + <para>Returns string.</para> + </refreturn> + </doc:template> + + <xsl:template name="str:substring-after-last"> + <xsl:param name="text"/> + <xsl:param name="chars"/> + + <xsl:choose> + + <xsl:when test="contains($text, $chars)"> + <xsl:variable name="last" select="substring-after($text, $chars)"/> + + <xsl:choose> + <xsl:when test="contains($last, $chars)"> + <xsl:call-template name="str:substring-after-last"> + <xsl:with-param name="text" select="$last"/> + <xsl:with-param name="chars" select="$chars"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$last"/> + </xsl:otherwise> + </xsl:choose> + </xsl:when> + + <xsl:otherwise> + <xsl:value-of select="$text"/> + </xsl:otherwise> + + </xsl:choose> + </xsl:template> + + <doc:template name="str:substring-before-last" xmlns=""> + <refpurpose>String extraction</refpurpose> + + <refdescription> + <para>Extracts the portion of string 'text' which occurs before the first character of the last occurance of string 'chars'.</para> + </refdescription> + + <refparameter> + <variablelist> + <varlistentry> + <term>text</term> + <listitem> + <para>The string from which to extract a substring.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>chars</term> + <listitem> + <para>The string containing characters to find.</para> + </listitem> + </varlistentry> + </variablelist> + </refparameter> + + <refreturn> + <para>Returns string.</para> + </refreturn> + </doc:template> + + <xsl:template name="str:substring-before-last"> + <xsl:param name="text"/> + <xsl:param name="chars"/> + + <xsl:choose> + + <xsl:when test="string-length($text) = 0"/> + + <xsl:when test="string-length($chars) = 0"> + <xsl:value-of select="$text"/> + </xsl:when> + + <xsl:when test="contains($text, $chars)"> + <xsl:call-template name="str:substring-before-last-aux"> + <xsl:with-param name="text" select="$text"/> + <xsl:with-param name="chars" select="$chars"/> + </xsl:call-template> + </xsl:when> + + <xsl:otherwise> + <xsl:value-of select="$text"/> + </xsl:otherwise> + + </xsl:choose> + </xsl:template> + + <xsl:template name="str:substring-before-last-aux"> + <xsl:param name="text"/> + <xsl:param name="chars"/> + + <xsl:choose> + <xsl:when test="string-length($text) = 0"/> + + <xsl:when test="contains($text, $chars)"> + <xsl:variable name="after"> + <xsl:call-template name="str:substring-before-last-aux"> + <xsl:with-param name="text" select="substring-after($text, $chars)"/> + <xsl:with-param name="chars" select="$chars"/> + </xsl:call-template> + </xsl:variable> + + <xsl:value-of select="substring-before($text, $chars)"/> + <xsl:if test="string-length($after) > 0"> + <xsl:value-of select="$chars"/> + <xsl:copy-of select="$after"/> + </xsl:if> + </xsl:when> + + <xsl:otherwise/> + </xsl:choose> + </xsl:template> + + <doc:template name="str:subst" xmlns=""> + <refpurpose>String substitution</refpurpose> + + <refdescription> + <para>Substitute 'replace' for 'with' in string 'text'.</para> + </refdescription> + + <refparameter> + <variablelist> + <varlistentry> + <term>text</term> + <listitem> + <para>The string upon which to perform substitution.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>replace</term> + <listitem> + <para>The string to substitute.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>with</term> + <listitem> + <para>The string to be substituted.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>disable-output-escaping</term> + <listitem> + <para>A value of <literal>yes</literal> indicates that the result should have output escaping disabled. Any other value allows normal escaping of text values. The default is to enable output escaping.</para> + </listitem> + </varlistentry> + </variablelist> + </refparameter> + + <refreturn> + <para>Returns string.</para> + </refreturn> + </doc:template> + + <xsl:template name="str:subst"> + <xsl:param name="text"/> + <xsl:param name="replace"/> + <xsl:param name="with"/> + <xsl:param name='disable-output-escaping'>no</xsl:param> + + <xsl:choose> + <xsl:when test="string-length($replace) = 0 and $disable-output-escaping = 'yes'"> + <xsl:value-of select="$text" disable-output-escaping='yes'/> + </xsl:when> + <xsl:when test="string-length($replace) = 0"> + <xsl:value-of select="$text"/> + </xsl:when> + <xsl:when test="contains($text, $replace)"> + + <xsl:variable name="before" select="substring-before($text, $replace)"/> + <xsl:variable name="after" select="substring-after($text, $replace)"/> + + <xsl:choose> + <xsl:when test='$disable-output-escaping = "yes"'> + <xsl:value-of select="$before" disable-output-escaping="yes"/> + <xsl:value-of select="$with" disable-output-escaping="yes"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$before"/> + <xsl:value-of select="$with"/> + </xsl:otherwise> + </xsl:choose> + <xsl:call-template name="str:subst"> + <xsl:with-param name="text" select="$after"/> + <xsl:with-param name="replace" select="$replace"/> + <xsl:with-param name="with" select="$with"/> + <xsl:with-param name="disable-output-escaping" select="$disable-output-escaping"/> + </xsl:call-template> + </xsl:when> + <xsl:when test='$disable-output-escaping = "yes"'> + <xsl:value-of select="$text" disable-output-escaping="yes"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$text"/> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <doc:template name="str:count-substring" xmlns=""> + <refpurpose>Count Substrings</refpurpose> + + <refdescription> + <para>Counts the number of times a substring occurs in a string. This can also counts the number of times a character occurs in a string, since a character is simply a string of length 1.</para> + </refdescription> + + <example> + <title>Counting Lines</title> + <programlisting><![CDATA[ +<xsl:call-template name="str:count-substring"> + <xsl:with-param name="text" select="$mytext"/> + <xsl:with-param name="chars" select="'
'"/> +</xsl:call-template> +]]></programlisting> + </example> + + <refparameter> + <variablelist> + <varlistentry> + <term>text</term> + <listitem> + <para>The source string.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>chars</term> + <listitem> + <para>The substring to count.</para> + </listitem> + </varlistentry> + </variablelist> + </refparameter> + + <refreturn> + <para>Returns a non-negative integer value.</para> + </refreturn> + </doc:template> + + <xsl:template name="str:count-substring"> + <xsl:param name="text"/> + <xsl:param name="chars"/> + + <xsl:choose> + <xsl:when test="string-length($text) = 0 or string-length($chars) = 0"> + <xsl:text>0</xsl:text> + </xsl:when> + <xsl:when test="contains($text, $chars)"> + <xsl:variable name="remaining"> + <xsl:call-template name="str:count-substring"> + <xsl:with-param name="text" select="substring-after($text, $chars)"/> + <xsl:with-param name="chars" select="$chars"/> + </xsl:call-template> + </xsl:variable> + <xsl:value-of select="$remaining + 1"/> + </xsl:when> + <xsl:otherwise> + <xsl:text>0</xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <doc:template name="str:substring-after-at" xmlns=""> + <refpurpose>String extraction</refpurpose> + <refdescription> + <para>Extracts the portion of a 'char' delimited 'text' string "array" at a given 'position'.</para> + </refdescription> + <refparameter> + <variablelist> + <varlistentry> + <term>text</term> + <listitem> + <para>The string from which to extract a substring.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>chars</term> + <listitem> + <para>delimiters</para> + </listitem> + </varlistentry> + <varlistentry> + <term>position</term> + <listitem> + <para>position of the elements</para> + </listitem> + </varlistentry> + <varlistentry> + <term>all</term> + <listitem> + <para>If true all of the remaining string is returned, otherwise only the element at the given position is returned. Default: false().</para> + </listitem> + </varlistentry> + </variablelist> + </refparameter> + <refreturn> + <para>Returns string.</para> + </refreturn> + </doc:template> + + + <xsl:template name="str:substring-after-at"> + <xsl:param name="text"/> + <xsl:param name="chars"/> + <xsl:param name="position"/> + <xsl:param name="all" select='false()'/> + + <xsl:choose> + <xsl:when test='number($position) = 0 and $all'> + <xsl:value-of select='$text'/> + </xsl:when> + <xsl:when test='number($position) = 0 and not($chars)'> + <xsl:value-of select='$text'/> + </xsl:when> + <xsl:when test='number($position) = 0 and not(contains($text, $chars))'> + <xsl:value-of select='$text'/> + </xsl:when> + <xsl:when test='not(contains($text, $chars))'> + </xsl:when> + <xsl:when test="number($position) = 0"> + <xsl:value-of select="substring-before($text, $chars)"/> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name="str:substring-after-at"> + <xsl:with-param name="text" select="substring-after($text, $chars)"/> + <xsl:with-param name="chars" select="$chars"/> + <xsl:with-param name="all" select="$all"/> + <xsl:with-param name="position" select="$position - 1"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <doc:template name="str:substring-before-at" xmlns=""> + <refpurpose>String extraction</refpurpose> + <refdescription> + <para>Extracts the portion of a 'char' delimited 'text' string "array" at a given 'position' </para> + </refdescription> + <refparameter> + <variablelist> + <varlistentry> + <term>text</term> + <listitem> + <para>The string from which to extract a substring.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>chars</term> + <listitem> + <para>delimiters</para> + </listitem> + </varlistentry> + <varlistentry> + <term>position</term> + <listitem> + <para>position of the elements</para> + </listitem> + </varlistentry> + </variablelist> + </refparameter> + <refreturn> + <para>Returns string.</para> + </refreturn> + </doc:template> + + <xsl:template name="str:substring-before-at"> + <xsl:param name="text"/> + <xsl:param name="chars"/> + <xsl:param name="position"/> + + <xsl:choose> + <xsl:when test="$position <= 0"/> + <xsl:when test="not(contains($text, $chars))"/> + <xsl:otherwise> + <xsl:value-of select='substring-before($text, $chars)'/> + <xsl:value-of select='$chars'/> + + <xsl:call-template name="str:substring-before-at"> + <xsl:with-param name="text" select="substring-after($text, $chars)"/> + <xsl:with-param name="position" select="$position - 1"/> + <xsl:with-param name="chars" select="$chars"/> + </xsl:call-template> + + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <doc:template name="str:insert-at" xmlns=""> + <refpurpose>String insertion</refpurpose> + <refdescription> + <para>Insert 'chars' into "text' at any given "position'</para> + </refdescription> + <refparameter> + <variablelist> + <varlistentry> + <term>text</term> + <listitem> + <para>The string upon which to perform insertion</para> + </listitem> + </varlistentry> + <varlistentry> + <term>position</term> + <listitem> + <para>the position where insertion will be performed</para> + </listitem> + </varlistentry> + <varlistentry> + <term>with</term> + <listitem> + <para>The string to be inserted</para> + </listitem> + </varlistentry> + </variablelist> + </refparameter> + <refreturn> + <para>Returns string.</para> + </refreturn> + </doc:template> + + <xsl:template name="str:insert-at"> + <xsl:param name="text"/> + <xsl:param name="position"/> + <xsl:param name="chars"/> + + <xsl:variable name="firstpart" select="substring($text, 0, $position)"/> + <xsl:variable name="secondpart" select="substring($text, $position, string-length($text))"/> + + <xsl:value-of select="concat($firstpart, $chars, $secondpart)"/> + </xsl:template> + + + <doc:template name="str:backward" xmlns=""> + <refpurpose>String reversal</refpurpose> + + <refdescription> + <para>Reverse the content of a given string</para> + </refdescription> + + <refparameter> + <variablelist> + <varlistentry> + <term>text</term> + <listitem> + <para>The string to be reversed</para> + </listitem> + </varlistentry> + </variablelist> + </refparameter> + + <refreturn> + <para>Returns string.</para> + </refreturn> + </doc:template> + + <xsl:template name="str:backward"> + <xsl:param name="text"/> + <xsl:variable name="mirror"> + <xsl:call-template name="str:build-mirror"> + <xsl:with-param name="text" select="$text"/> + <xsl:with-param name="position" select="string-length($text)"/> + </xsl:call-template> + </xsl:variable> + <xsl:value-of select="substring($mirror, string-length($text) + 1, string-length($text))"/> + </xsl:template> + + <xsl:template name="str:build-mirror"> + <xsl:param name="text"/> + <xsl:param name="position"/> + + <xsl:choose> + <xsl:when test="$position > 0"> + <xsl:call-template name="str:build-mirror"> + <xsl:with-param name="text" select="concat($text, substring($text, $position, 1))"/> + <xsl:with-param name="position" select="$position - 1"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$text"/> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <doc:template name="str:justify" xmlns=""> + <refpurpose>Format a string</refpurpose> + + <refdescription> + <para>Inserts newlines and spaces into a string to format it as a block of text.</para> + </refdescription> + + <refparameter> + <variablelist> + <varlistentry> + <term>text</term> + <listitem> + <para>String to be formatted.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>max</term> + <listitem> + <para>Maximum line length.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>indent</term> + <listitem> + <para>Number of spaces to insert at the beginning of each line.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>justify</term> + <listitem> + <para>Justify left, right or both. Not currently implemented (fixed at "left").</para> + </listitem> + </varlistentry> + </variablelist> + </refparameter> + + <refreturn> + <para>Formatted block of text.</para> + </refreturn> + </doc:template> + + <xsl:template name='str:justify'> + <xsl:param name='text'/> + <xsl:param name='max' select='"80"'/> + <xsl:param name='indent' select='"0"'/> + <xsl:param name='justify' select='"left"'/> + + <xsl:choose> + <xsl:when test='string-length($text) = 0 or $max <= 0'/> + + <xsl:when test='string-length($text) > $max and contains($text, " ") and string-length(substring-before($text, " ")) > $max'> + <xsl:call-template name='str:generate-string'> + <xsl:with-param name='text' select='" "'/> + <xsl:with-param name='count' select='$indent'/> + </xsl:call-template> + <xsl:value-of select='substring-before($text, " ")'/> + <xsl:text> +</xsl:text> + <xsl:call-template name='str:justify'> + <xsl:with-param name='text' select='substring-after($text, " ")'/> + <xsl:with-param name='max' select='$max'/> + <xsl:with-param name='indent' select='$indent'/> + <xsl:with-param name='justify' select='$justify'/> + </xsl:call-template> + </xsl:when> + + <xsl:when test='string-length($text) > $max and contains($text, " ")'> + <xsl:variable name='first'> + <xsl:call-template name='str:substring-before-last'> + <xsl:with-param name='text' select='substring($text, 1, $max)'/> + <xsl:with-param name='chars' select='" "'/> + </xsl:call-template> + </xsl:variable> + + <xsl:call-template name='str:generate-string'> + <xsl:with-param name='text' select='" "'/> + <xsl:with-param name='count' select='$indent'/> + </xsl:call-template> + <xsl:value-of select='$first'/> + <xsl:text> +</xsl:text> + <xsl:call-template name='str:justify'> + <xsl:with-param name='text' select='substring($text, string-length($first) + 2)'/> + <xsl:with-param name='max' select='$max'/> + <xsl:with-param name='indent' select='$indent'/> + <xsl:with-param name='justify' select='$justify'/> + </xsl:call-template> + </xsl:when> + + <xsl:otherwise> + <xsl:call-template name='str:generate-string'> + <xsl:with-param name='text' select='" "'/> + <xsl:with-param name='count' select='$indent'/> + </xsl:call-template> + <xsl:value-of select='$text'/> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <doc:template name="str:character-first" xmlns=""> + <refpurpose>Find first occurring character in a string</refpurpose> + + <refdescription> + <para>Finds which of the given characters occurs first in a string.</para> + </refdescription> + + <refparameter> + <variablelist> + <varlistentry> + <term>text</term> + <listitem> + <para>The source string.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>chars</term> + <listitem> + <para>The characters to search for.</para> + </listitem> + </varlistentry> + </variablelist> + </refparameter> + </doc:template> + + <xsl:template name="str:character-first"> + <xsl:param name="text"/> + <xsl:param name="chars"/> + + <xsl:choose> + <xsl:when test="string-length($text) = 0 or string-length($chars) = 0"/> + + <xsl:when test="contains($text, substring($chars, 1, 1))"> + <xsl:variable name="next-character"> + <xsl:call-template name="str:character-first"> + <xsl:with-param name="text" select="$text"/> + <xsl:with-param name="chars" select="substring($chars, 2)"/> + </xsl:call-template> + </xsl:variable> + + <xsl:choose> + <xsl:when test="string-length($next-character)"> + <xsl:variable name="first-character-position" select="string-length(substring-before($text, substring($chars, 1, 1)))"/> + <xsl:variable name="next-character-position" select="string-length(substring-before($text, $next-character))"/> + + <xsl:choose> + <xsl:when test="$first-character-position < $next-character-position"> + <xsl:value-of select="substring($chars, 1, 1)"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$next-character"/> + </xsl:otherwise> + </xsl:choose> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="substring($chars, 1, 1)"/> + </xsl:otherwise> + </xsl:choose> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name="str:character-first"> + <xsl:with-param name="text" select="$text"/> + <xsl:with-param name="chars" select="substring($chars, 2)"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <doc:template name="str:string-match" xmlns=""> + <refpurpose>Match A String To A Pattern</refpurpose> + + <refdescription> + <para>Performs globbing-style pattern matching on a string.</para> + </refdescription> + + <example> + <title>Match Pattern</title> + <programlisting><![CDATA[ +<xsl:call-template name="str:string-match"> + <xsl:with-param name="text" select="$mytext"/> + <xsl:with-param name="pattern" select="'abc*def?g'"/> +</xsl:call-template> +]]></programlisting> + </example> + + <refparameter> + <variablelist> + <varlistentry> + <term>text</term> + <listitem> + <para>The source string.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>pattern</term> + <listitem> + <para>The pattern to match against. Certain characters have special meaning:</para> + <variablelist> + <varlistentry> + <term>*</term> + <listitem> + <para>Matches zero or more characters.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>?</term> + <listitem> + <para>Matches a single character.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>\</term> + <listitem> + <para>Character escape. The next character is taken as a literal character.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + </refparameter> + + <refreturn> + <para>Returns "1" if the string matches the pattern, "0" otherwise.</para> + </refreturn> + </doc:template> + + <xsl:template name="str:string-match"> + <xsl:param name="text"/> + <xsl:param name="pattern"/> + + <xsl:choose> + <xsl:when test="$pattern = '*'"> + <!-- Special case: always matches --> + <xsl:text>1</xsl:text> + </xsl:when> + <xsl:when test="string-length($text) = 0 and string-length($pattern) = 0"> + <xsl:text>1</xsl:text> + </xsl:when> + <xsl:when test="string-length($text) = 0 or string-length($pattern) = 0"> + <xsl:text>0</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:variable name='before-special'> + <xsl:call-template name='str:substring-before-first'> + <xsl:with-param name='text' select='$pattern'/> + <xsl:with-param name='chars' select='"*?\"'/> + </xsl:call-template> + </xsl:variable> + <xsl:variable name='special'> + <xsl:call-template name='str:character-first'> + <xsl:with-param name='text' select='$pattern'/> + <xsl:with-param name='chars' select='"*?\"'/> + </xsl:call-template> + </xsl:variable> + + <xsl:variable name='new-text' select='substring($text, string-length($before-special) + 1)'/> + <xsl:variable name='new-pattern' select='substring($pattern, string-length($before-special) + 1)'/> + + <xsl:choose> + <xsl:when test="not(starts-with($text, $before-special))"> + <!-- Verbatim characters don't match --> + <xsl:text>0</xsl:text> + </xsl:when> + + <xsl:when test="$special = '*' and string-length($new-pattern) = 1"> + <xsl:text>1</xsl:text> + </xsl:when> + <xsl:when test="$special = '*'"> + <xsl:call-template name='str:match-postfix'> + <xsl:with-param name='text' select='$new-text'/> + <xsl:with-param name='pattern' select='substring($new-pattern, 2)'/> + </xsl:call-template> + </xsl:when> + + <xsl:when test="$special = '?'"> + <xsl:call-template name="str:string-match"> + <xsl:with-param name='text' select='substring($new-text, 2)'/> + <xsl:with-param name='pattern' select='substring($new-pattern, 2)'/> + </xsl:call-template> + </xsl:when> + + <xsl:when test="$special = '\' and substring($new-text, 1, 1) = substring($new-pattern, 2, 1)"> + <xsl:call-template name="str:string-match"> + <xsl:with-param name='text' select='substring($new-text, 2)'/> + <xsl:with-param name='pattern' select='substring($new-pattern, 3)'/> + </xsl:call-template> + </xsl:when> + <xsl:when test="$special = '\' and substring($new-text, 1, 1) != substring($new-pattern, 2, 1)"> + <xsl:text>0</xsl:text> + </xsl:when> + + <xsl:otherwise> + <!-- There were no special characters in the pattern --> + <xsl:choose> + <xsl:when test='$text = $pattern'> + <xsl:text>1</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>0</xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:otherwise> + </xsl:choose> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <xsl:template name="str:match-postfix"> + <xsl:param name="text"/> + <xsl:param name="pattern"/> + + <xsl:variable name='result'> + <xsl:call-template name='str:string-match'> + <xsl:with-param name='text' select='$text'/> + <xsl:with-param name='pattern' select='$pattern'/> + </xsl:call-template> + </xsl:variable> + + <xsl:choose> + <xsl:when test='$result = "1"'> + <xsl:value-of select='$result'/> + </xsl:when> + <xsl:when test='string-length($text) = 0'> + <xsl:text>0</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name='str:match-postfix'> + <xsl:with-param name='text' select='substring($text, 2)'/> + <xsl:with-param name='pattern' select='$pattern'/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> + + </xsl:template> + + <doc:template name="str:generate-string" xmlns=""> + <refpurpose>Create A Repeating Sequence of Characters</refpurpose> + + <refdescription> + <para>Repeats a string a given number of times.</para> + </refdescription> + + <refparameter> + <variablelist> + <varlistentry> + <term>text</term> + <listitem> + <para>The string to repeat.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>count</term> + <listitem> + <para>The number of times to repeat the string.</para> + </listitem> + </varlistentry> + </variablelist> + </refparameter> + </doc:template> + + <xsl:template name="str:generate-string"> + <xsl:param name="text"/> + <xsl:param name="count"/> + + <xsl:choose> + <xsl:when test="string-length($text) = 0 or $count <= 0"/> + <xsl:otherwise> + <xsl:value-of select="$text"/> + <xsl:call-template name="str:generate-string"> + <xsl:with-param name="text" select="$text"/> + <xsl:with-param name="count" select="$count - 1"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + +</xsl:stylesheet> + diff --git a/doc/manual/titlepage-htmlhelp.xml b/doc/manual/titlepage-htmlhelp.xml new file mode 100644 index 00000000..cfcf39b8 --- /dev/null +++ b/doc/manual/titlepage-htmlhelp.xml @@ -0,0 +1,669 @@ +<!-- This file is taken from Docbook Project as available + from http://docbook.sourceforge.net/ (version 1.69.1, + file titlepage.templates.xml. + It was slightly modified. --> + +<t:templates xmlns:t="http://nwalsh.com/docbook/xsl/template/1.0" + xmlns:param="http://nwalsh.com/docbook/xsl/template/1.0/param" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> + +<!-- ==================================================================== --> + +<t:titlepage t:element="article" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + <hr/> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="set" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + <hr/> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="book" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <edition/> + <corpauthor/> + <authorgroup/> + <author/> + <address/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + <hr/> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="part" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="division.title" + param:node="ancestor-or-self::part[1]"/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<t:titlepage t:element="partintro" t:wrapper="div"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="reference" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + <hr/> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="refentry" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> +<!-- uncomment this if you want refentry titlepages + <title t:force="1" + t:named-template="refentry.title" + param:node="ancestor-or-self::refentry[1]"/> +--> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator/> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + + <t:titlepage t:element="dedication" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="component.title" + param:node="ancestor-or-self::dedication[1]"/> + <subtitle/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="preface" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="chapter" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="appendix" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="section" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + <xsl:if test="count(parent::*)='0'"><hr/></xsl:if> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<t:titlepage t:element="sect1" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + <xsl:if test="count(parent::*)='0'"><hr/></xsl:if> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<t:titlepage t:element="sect2" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + <xsl:if test="count(parent::*)='0'"><hr/></xsl:if> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<t:titlepage t:element="sect3" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + <xsl:if test="count(parent::*)='0'"><hr/></xsl:if> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<t:titlepage t:element="sect4" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + <xsl:if test="count(parent::*)='0'"><hr/></xsl:if> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<t:titlepage t:element="sect5" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + <xsl:if test="count(parent::*)='0'"><hr/></xsl:if> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<t:titlepage t:element="simplesect" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + <xsl:if test="count(parent::*)='0'"><hr/></xsl:if> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="bibliography" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="component.title" + param:node="ancestor-or-self::bibliography[1]"/> + <subtitle/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="glossary" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="component.title" + param:node="ancestor-or-self::glossary[1]"/> + <subtitle/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="index" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="component.title" + param:node="ancestor-or-self::index[1]"/> + <subtitle/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="setindex" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="component.title" + param:node="ancestor-or-self::setindex[1]"/> + <subtitle/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +</t:templates> diff --git a/doc/manual/user_ChangeLogImpl.xml b/doc/manual/user_ChangeLogImpl.xml new file mode 100644 index 00000000..caebf791 --- /dev/null +++ b/doc/manual/user_ChangeLogImpl.xml @@ -0,0 +1,931 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<!-- +Release change log structure + +Each release has a matching log of changes which were made for that and +earlier releases. Earlier releases means anything with a lower number (e.g. +5.0.18 is lower than 5.1.2) which was released before this one. The log is +kept in the file doc/manual/user_ChangeLogImpl.xml. Anything worth mentioning, +particularly new features and fixed bugs, with a trac bug number if possible, +should be added to the top of the change log (that is, the section for the +upcoming release) for the branch in which it first appears - stable or +development - before the next release. If you back-port it to older branches +please add an entry there too. When a new major release is made, change log +sections for earlier releases are merged in. + +Change log sections are split into two groups: major new features (normally +only for dot zero releases) and fixes. In addition, the entries in each group +are ordered as follows: + + VMM-related entries (most important) + GUI-related entries (most visible for users) + Device-related entries + VBoxManage/API/Main-related entries + Host-related entries + Guest-related entries + BIOS/EFI/ACPI-related entries + +Please do further ordering as seems appropriate by importance and visibility for +users, e.g. audio before serial ports and generally Windows before Linux. Please +also try to describe the user impact, not the technical details, and only use +technical terms if no non-technical ones are clear enough. + +Rules for adding a changelog entry to make them look more uniform: + + 1. Begin the entry with an UPPERCASE letter, e.g. "Foo: Fixed" vs. "Foo: fixed" + 2. Use the past form of something, e.g. "Fixed ..." vs. "Fix ..." + 3. No dot (.) after the entry, e.g. "<para>Foo: Bar</para>" vs. "<para>Foo: Bar.</para>" + 4. Use TWO (2) spaces for indentation + 5. Use line breaks when hitting column 80 + + Full example: + + <listitem> + <para>Foo: Fixed something really important, really really long line + with lots more text not fitting into 80 columns</para> + </listitem> +--> +<chapter> + +<!-- HACK ALERT! Seems we must have a single top level element for xi:include to work. + So, we use chapter and xpointer="xpointer(/chapter/)" with xi:include. --> + <sect1> + + <title>Version 7.0.14 (2024-01-16)</title> + + <para>This is a maintenance release. The following items were fixed and/or + added:</para> + + <itemizedlist> + + <listitem> + <para>Audio: Added more fixes for switching host audio devices on Windows + hosts using the WAS backend</para> + </listitem> + + <listitem> + <para>3D: Added general improvements</para> + </listitem> + + <listitem> + <para>OCI: Fixed wrong guest RAM unit usage in VirtualSystemDescription, + memory is provided in bytes, "Byte" is the base unit</para> + </listitem> + + <listitem> + <para>Main: OVF Import/Export: Added support for importing and exporting + VMs containing NVMe storage controllers (bug #19320)</para> + </listitem> + + <listitem> + <para>Main: OVF Import/Export: Added support for exporting a VM which + contains a medium inserted into a virtual CD/DVD drive which is attached + to a Virtio-SCSI controller</para> + </listitem> + + <listitem> + <para>Devices: Fixed a problem where Windows guests "forget" in-progress + touch events when the user holds down a finger without moving it for + a period of time.</para> + </listitem> + + <listitem> + <para>macOS Host USB: Added support for newer storage devices</para> + </listitem> + + <listitem> + <para>macOS Host: Fixed memory Leak in the VBoxIntNetSwitch process when VM + was configured to use 'Internal Networking' (bug #21752)</para> + </listitem> + + <listitem> + <para>Linux Host and Guest: Added initial support for RHEL 9.4 kernel</para> + </listitem> + + <listitem> + <para>Linux Guest Additions: Fixed kernel panic on RHEL 8.9 kernel + caused by vboxvideo (bugs #10381 and #21911)</para> + </listitem> + + <listitem> + <para>Solaris Guest Additions: Added support for the Additions to be installed + into an alternate root path ('pkgadd -R')</para> + </listitem> + + <listitem> + <para>Solaris Guest Additions: Removed requirement to reboot VM after uninstalling GAs</para> + </listitem> + + <listitem> + <para>RDP: Fix possible crash when connecting with the Apple Silicon + variant of the Microsoft Remote Desktop application (bug #21820).</para> + </listitem> + + <listitem> + <para>BIOS: Fixed handle number used for DMI OEM table (bug #19781)</para> + </listitem> + + </itemizedlist> + </sect1> + + <sect1> + + <title>Version 7.0.12 (2023-10-17)</title> + + <para>This is a maintenance release. The following items were fixed and/or + added:</para> + + <itemizedlist> + + <listitem> + <para>VMM: Fixed using a debugger inside the guest under certain + circumstances (bugs #21413 and #21546)</para> + </listitem> + + <listitem> + <para>VMM: Fixed detection of VT-x being used by other hypervisors (bug #21867)</para> + </listitem> + + <listitem> + <para>VMM: Introduced additional improvements in Split Lock Detection feature of + recent Intel CPUs on Linux hosts (bug #20180)</para> + </listitem> + + <listitem> + <para>GUI: Fixed issue when the nested hardware virtualization setting + was not displayed in the VM details panel (bug #21707)</para> + </listitem> + + <listitem> + <para>GUI: Introduced NLS update for Croatian, Indonesian, Italian, + Japanese, Korean, Dutch and Turkish languages as well as added + general look-and-feel improvements</para> + </listitem> + + <listitem> + <para>Devices: Fixed black screen in Windows guests with multiple guest + screens when 3D is disabled (7.0.10 regression)</para> + </listitem> + + <listitem> + <para>Devices: Fixed PCI device identifiers for the VirtIO network interface + (bug #21516)</para> + </listitem> + + <listitem> + <para>Devices: Fixed VLAN support for the VirtIO network interface + (bug #21778)</para> + </listitem> + + <listitem> + <para>Devices: Fixed loading saved states when a TPM is configured + (7.0.10 regression, bug #21773)</para> + </listitem> + + <listitem> + <para>Networking: Fixed memory leaks in the VBoxIntNetSwitch process + on macOS (bug #21752)</para> + </listitem> + + <listitem> + <para>Networking: Fixed TCP connections with IP addresses ending on .2 + when the NAT network attachment is used (bug #21513)</para> + </listitem> + + <listitem> + <para>Audio: Fixed switching host audio devices on Windows hosts + using the WAS backend (bugs #20431, #21517, #20630 and #20723)</para> + </listitem> + + <listitem> + <para>VRDP: Added general improvements</para> + </listitem> + + <listitem> + <para>VBoxManage: Added improvements for "list usbfilters" command</para> + </listitem> + + <listitem> + <para>Unattended: Added kick start file support for Oracle Linux 8 and Oracle Linux 9.</para> + </listitem> + + <listitem> + <para>Main: Added more Linux OS subtypes</para> + </listitem> + + <listitem> + <para>Host Services: Fixed Guest Properties service crash under rare + circumstance</para> + </listitem> + + <listitem> + <para>Linux Host and Guest: Fixed few "field-spanning write" kernel + warnings (bugs #21410 and #21862)</para> + </listitem> + + <listitem> + <para>Linux Guest Additions: Added more fixes for RHEL 8.9 and 9.3 kernel</para> + </listitem> + + <listitem> + <para>Linux Guest Additions: Added more fixes for kernel 6.4</para> + </listitem> + + <listitem> + <para>Linux Guest Additions: Added initial support for OpenSUSE 15.5 kernel</para> + </listitem> + + <listitem> + <para>Linux Guest Additions: Added initial support for kernels 6.5 and 6.6</para> + </listitem> + + <listitem> + <para>Linux Guest Additions: Added version reporting for "rcvboxadd status-kernel" + and "rcvboxadd status-user" commands</para> + </listitem> + + <listitem> + <para>BIOS: Restored support for ISA SCSI HBAs in the BIOS (bug #21736)</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + + <title>Version 7.0.10 (2023-07-18)</title> + + <para>This is a maintenance release. The following items were fixed and/or + added:</para> + + <itemizedlist> + + <listitem> + <para>OCI: Introduced general improvements</para> + </listitem> + + <listitem> + <para>VMM: Fixed sluggish performance starting with macOS Ventura 13.3 (bug #21563, bug#21596)</para> + </listitem> + + <listitem> + <para>VMM: Fixed a bug while walking page tables while executing nested VMs causing flooding of + the release log as a consequence (Intel hosts only, bug #21551)</para> + </listitem> + + <listitem> + <para>GUI: Added general improvements</para> + </listitem> + + <listitem> + <para>TPM: Fixed a crash when a VM has a TPM version 1.2 configured (bug #21622)</para> + </listitem> + + <listitem> + <para>3D: Initial support for OpenGL 4.1</para> + </listitem> + + <listitem> + <para>3D: Fixed various graphics issues with Windows 11 guests + (bugs #21136, #21515)</para> + </listitem> + + <listitem> + <para>Guest Control/VBoxManage: Fixed parameter "--ignore-orphaned-processes"</para> + </listitem> + + <listitem> + <para>Guest Control/VBoxManage: One can now explicitly specify an executable + argument 0 via "--arg0" with the "run" and "start" commands. See VBoxManage + help for examples</para> + </listitem> + + <listitem> + <para>Audio: Also use the PulseAudio backend when pipewire-pulse is running + instead of falling back to ALSA (bug #21575)</para> + </listitem> + + <listitem> + <para>NAT: Adjusted UDP proxy timeout from 18-21 to 21-24 range to respect + intended 20 second timeout (bug #21560)</para> + </listitem> + + <listitem> + <para>Linux Host: Added initial support for Indirect Branch Tracking (bug #21435)</para> + </listitem> + + <listitem> + <para>Linux Host: Added initial support for kernel 6.5 (NOTE: Guest Additions + do not support kernel 6.5 yet)</para> + </listitem> + + <listitem> + <para>Solaris Host: Introduced general improvements in the installer area</para> + </listitem> + + <listitem> + <para>Linux Host and Guest: Improved condition check when kernel modules need + to be signed</para> + </listitem> + + <listitem> + <para>Linux Host and Guest: Added initial support for RHEL 8.8 (bug #21692), + 8.9 (bug #21690) and 9.3 (bugs #21598 and #21671) kernels</para> + </listitem> + + <listitem> + <para>MacOS Host and Guest: Introduced general improvements in the installer area</para> + </listitem> + + <listitem> + <para>Windows Host and Guest: Introduced ECDSA support (bug #21621)</para> + </listitem> + + <listitem> + <para>Linux Guest Additions: Fixed issue when kernel modules were rebuilt on each boot + when guest system has no X11 installed</para> + </listitem> + + <listitem> + <para>Linux Guest Additions: Added initial support for kernel 6.4</para> + </listitem> + + <listitem> + <para>Linux Guest Additions: Fixed issue when vboxvideo module reloading + caused kernel panic in some guests (bug #21740)</para> + </listitem> + + <listitem> + <para>Linux Guest Additions: Introduced general improvements in the + installer area</para> + </listitem> + + <listitem> + <para>Windows Guest Additions: Introduced general improvements in graphics + drivers area</para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1> + + <title>Version 7.0.8 (2023-04-18)</title> + + <para>This is a maintenance release. The following items were fixed and/or + added:</para> + + <itemizedlist> + + <listitem> + <para>VMM: Fixed EFLAGS.TF handling for CPUID instructions when Hyper-V is used (bug #17961)</para> + </listitem> + + <listitem> + <para>VMM: Fixed MONITOR/MWAIT crash with Solaris guests when Hyper-V is used on Windows 11</para> + </listitem> + + <listitem> + <para>VMM: Introduced general improvements in nested visualization area</para> + </listitem> + + <listitem> + <para>VMM: Fixed triple fault related guru meditations for UEFI guests starting with + macOS Ventura 13.3 (bug #21563)</para> + </listitem> + + <listitem> + <para>GUI: Brought back Restore current snapshot checkbox of Close VM dialog (bugs #21189, #21491)</para> + </listitem> + + <listitem> + <para>GUI: Fixes and validation for VM settings USB filters editor, filter port value is now properly + saved/restored</para> + </listitem> + + <listitem> + <para>GUI: Fixes for VM name and OS type embedded editors of Details pane</para> + </listitem> + + <listitem> + <para>GUI: Cloud related wizards should now propose enabled profiles before disabled</para> + </listitem> + + <listitem> + <para>Oracle VM VirtualBox Extension Pack: Fixed shipping the cryptographic support module for full VM encryption</para> + </listitem> + + <listitem> + <para>E1000: Fixed possible guru meditation when changing network attachments (bug #21488)</para> + </listitem> + + <listitem> + <para>virtio-net: Follow up fixes for FreeBSD 12.3 and pfSense 2.6.0 (bug #21201)</para> + </listitem> + + <listitem> + <para>3D: Fixed various graphics issues with Windows 7 guests + (bugs #21129, #21196, #21208, #21521)</para> + </listitem> + + <listitem> + <para>Main/UefiVariableStore: Added API to add signatures to the MOK + list (Machine Owner Key)</para> + </listitem> + + <listitem> + <para>VBoxManage: Introduced modifynvram enrollmok sub-command to enroll Machine + Owner Key into NVRAM, so Linux guest kernel can pick it up in order to verify + signature of modules signed with this key</para> + </listitem> + + <listitem> + <para>Guest Control/Main: Fixed deleting files via built-in toolbox</para> + </listitem> + + <listitem> + <para>Linux host: Added possibility to bypass kernel modules signature verification + once VBOX_BYPASS_MODULES_SIGNATURE_CHECK="1" is specified in /etc/vbox/vbox.cfg, + useful in case if Linux distribution does not provide necessary tools to verify + kernel module signature</para> + </listitem> + + <listitem> + <para>Linux Guest Additions and host Installer: Improved detection if system is + running systemd as the init process</para> + </listitem> + + <listitem> + <para>Linux Guest Additions and host drivers: Introduce initial support for kernel 6.3</para> + </listitem> + + <listitem> + <para>Linux Guest Additions: Added possibility to bypass kernel modules signature + verification once VBOX_BYPASS_MODULES_SIGNATURE_CHECK="1" is specified + in /etc/virtualbox-guest-additions.conf, useful in case if Linux distribution + does not provide necessary tools to verify kernel module signature</para> + </listitem> + + <listitem> + <para>Linux Guest Additions: Added experimental support for kernel modules and + user services reloading in the end of installation process, thus guest system + reboot after Guest Additions (7.0.8 and newer) upgrade is no longer required + in general case</para> + </listitem> + + <listitem> + <para>Linux Guest Additions: Fixed vboxvideo build issue + with RHEL 8.7, 9.1 and 9.2 kernels (bugs #21446 and #21450)</para> + </listitem> + + </itemizedlist> + </sect1> + + <sect1> + + <title>Version 7.0.6 (2023-01-17)</title> + + <para>This is a maintenance release. The following items were fixed and/or + added:</para> + + <itemizedlist> + + <listitem> + <para>VMM: Fixed guru running the FreeBSD loader on older Intel CPUs + without unrestricted guest support (bug #21332)</para> + </listitem> + + <listitem> + <para>GUI: Fixed virtual machines grouping when VM was created or + modified in command line (bugs #11500, #20933)</para> + </listitem> + + <listitem> + <para>GUI: Introduced generic changes in settings dialogs</para> + </listitem> + + <listitem> + <para>VirtioNet: Fixed broken network after loading saved state + (bug #21172)</para> + </listitem> + + <listitem> + <para>Storage: Added support for increasing the size of the following + VMDK image variants: monolithicFlat, monolithicSparse, twoGbMaxExtentSparse, + twoGbMaxExtentFlat</para> + </listitem> + + <listitem> + <para>VBoxManage: Added missing --directory switch for guestcontrol mktemp command</para> + </listitem> + + <listitem> + <para>Mouse Integration: Guest was provided with extended host mouse state (bug #21139)</para> + </listitem> + + <listitem> + <para>DnD: Introduced generic improvements</para> + </listitem> + + <listitem> + <para>Guest Control: Fixed handling creation mode for temporary directories + (bug #21394)</para> + </listitem> + + <listitem> + <para>Linux Host and Guest: Added initial support for building UEK7 kernel on + Oracle Linux 8</para> + </listitem> + + <listitem> + <para>Linux Host and Guest: Added initial support for RHEL 9.1 kernel</para> + </listitem> + + <listitem> + <para>Windows Host: Fixed support for VM autostart (bug#21349)</para> + </listitem> + + <listitem> + <para>Linux Guest Additions: Added initial support for kernel 6.2 for vboxvideo</para> + </listitem> + + <listitem> + <para>Audio: The "--audio" option in VBoxManage is now marked as + deprecated; please use "--audio-driver" and "--audio-enabled" + instead. This will allow more flexibility when changing the driver + and/or controlling the audio functionality</para> + </listitem> + + </itemizedlist> + </sect1> + + <sect1> + + <title>Version 7.0.4 (2022-11-18)</title> + + <para>This is a maintenance release. The following items were fixed and/or + added:</para> + + <itemizedlist> + + <listitem> + <para>VMM: Added nested paging support for nested virtualization (Intel hosts only)</para> + </listitem> + + <listitem> + <para>VMM: Fixed rare guru meditations with certain guests on macOS 10.15 (Catalina) (bug #21237)</para> + </listitem> + + <listitem> + <para>VMM: Fixed possible VM process crash on Windows hosts when Hyper-V is used with certain guests (bug #21174)</para> + </listitem> + + <listitem> + <para>VMM: Fixed Windows XP guest hang or BSOD on AMD CPUs under certain circumstances (bug #21256)</para> + </listitem> + + <listitem> + <para>GUI: Various bugfixes for the Guest Control file manager</para> + </listitem> + + <listitem> + <para>GUI: Added more informative file operations in the Guest Control file manager</para> + </listitem> + + <listitem> + <para>GUI: Added an option to the global settings (the display page) to resize user interface font</para> + </listitem> + + <listitem> + <para>GUI: Fixed a regression in new vm wizard. Selected virtual disks are no longer deleted when the wizard + is cancelled (bug #21244)</para> + </listitem> + + <listitem> + <para>GUI: Added a new menu item to the devices menu to optionally upgrade the guest additions.</para> + </listitem> + + <listitem> + <para>VirtioSCSI: Fixed recognition of the virtio SCSI controller by the EFI firmware (bug #21200)</para> + </listitem> + + <listitem> + <para>VirtioSCSI: Fixed hang when shutting down the VM if the virtio SCSI controller is used (bug #21144)</para> + </listitem> + + <listitem> + <para>virtio-net: Workaround a bug in the virtio-net driver included in FreeBSD version up to 12.3 + which renders the device non functional (bug #21201)</para> + </listitem> + + <listitem> + <para>Storage: Fixed I/O errors with the VirtioSCSI controller when the host I/O cache is enabled (bug #19717)</para> + </listitem> + + <listitem> + <para>VBoxManage: Fixed regression when 'createmedium disk --variant RawDisk' command resulted + in invalid .vmdk file (bug #21125)</para> + </listitem> + + <listitem> + <para>Main: Restored input pointing device behavior in multi-monitor + VM configuration (bug #21137)</para> + </listitem> + + <listitem> + <para>Main: Fixed progress indication during automatic Linux + Guest Additions installation</para> + </listitem> + + <listitem> + <para>Guest Control: Fixed path handling issues (bug #21095)</para> + </listitem> + + <listitem> + <para>3D: Fixed VM process crash on macOS with 3D enabled (bug #21232)</para> + </listitem> + + <listitem> + <para>Linux Host and Guest: General improvements in startup scripts</para> + </listitem> + + <listitem> + <para>Linux Guest Additions: Introduced initial support for + RHEL 8.7 and 9.2 kernels (bug #21272, #21258)</para> + </listitem> + + <listitem> + <para>Linux Guest Additions: Introduced initial support for SLES 15.4 kernels</para> + </listitem> + + <listitem> + <para>Linux Guest Additions: Fixed kernel modules rebuild behavior on + system shutdown</para> + </listitem> + + </itemizedlist> + </sect1> + + <sect1> + + <title>Version 7.0.2 (2022-10-20)</title> + + <para>This is a maintenance release. The following items were fixed and/or + added:</para> + + <itemizedlist> + + <listitem> + <para>Known issue: VMs having more than one vCPU configured will not work properly on macOS + Catalina due to an unknown memory corruption issue. Either lower the number of vCPUs to 1 + or upgrade to BigSur or later where the issue does not occur</para> + </listitem> + + <listitem> + <para>Main: Fixed issue when VBoxSVC could become unresponsive if Extension Pack + was not installed (bug #21167)</para> + </listitem> + + <listitem> + <para>macOS hosts: Added workaround for a bug in the Hypervisor framework on Catalina causing + VERR_NEM_MAP_PAGES_FAILED errors when starting a VM. (bug #21128)</para> + </listitem> + + <listitem> + <para>macOS hosts: Re-introduced support for internal networking, this is considered a bit + experimental still</para> + </listitem> + + <listitem> + <para>macOS hosts: Fixed VM crash when the guest tries to access a microphone or webcam</para> + </listitem> + + <listitem> + <para>Windows host: Shared Clipboard: Fixed issue when only 4Kb of host + clipboard buffer was accessible to guest (bug #21149)</para> + </listitem> + + <listitem> + <para>Linux Guest Additions: Introduced initial support for kernel 6.1</para> + </listitem> + + <listitem> + <para>Linux Guest Additions: Fixed issue when VBoxClient seamless service + caused a crash of some X11 applications (bug #21132)</para> + </listitem> + + <listitem> + <para>Windows hosts: GUI: Fixed missing Qt libraries for vista style and sql driver (bug #21155)</para> + </listitem> + + <listitem> + <para>GUI: Fixed a glitch in the log viewer which was causing wrong log file to be saved (bug #21156)</para> + </listitem> + + </itemizedlist> + </sect1> + + <sect1> + + <title>Version 7.0.0 (2022-10-10)</title> + + <para>This is a major update. The following major new features were added:</para> + + <itemizedlist> + + <listitem> + <para>Virtual machines can be fully encrypted now, including the VM config logs + and saved states (CLI only for now)</para> + </listitem> + + <listitem> + <para>OCI: Cloud virtual machines can be added to Virtual Machine Manager and controlled + as local VMs</para> + </listitem> + + <listitem> + <para>OCI: Cloud networks can now be configured via Network Manager tool same way as + it is done for Host-only and NAT networks</para> + </listitem> + + <listitem> + <para>GUI: Added a new utility similar to "top" or "resource monitor" which lists peformance statistics + (CPU usage, RAM usage, disk I/O rate, etc.) of running guests</para> + </listitem> + + <listitem> + <para>GUI: Reworked the new vm wizard to integrate the unattended + guest OS installation and to have a more streamlined work flow</para> + </listitem> + + <listitem> + <para>GUI: Added a new help viewer widget which enables the user manual to be navigated + and searched</para> + </listitem> + + <listitem> + <para>GUI: Adding new notification center unifying most of running progresses and error + reporting around the GUI</para> + </listitem> + + <listitem> + <para>GUI: Improved theme support on all platforms. Linux and macOS + use native engine while for Windows host it is separately implemented.</para> + </listitem> + + <listitem> + <para>GUI: Large icon update.</para> + </listitem> + + <listitem> + <para>Audio recording: Now using Vorbis as the default audio format for WebM containers. + Opus is no longer being used.</para> + </listitem> + + <listitem> + <para>Audio: Added "default" host driver type to make it possible to move VMs (appliances) between different platforms + without the need of changing the audio driver explicitly. When the "default" driver is selected, the best audio backend + option for a platform will be used. This is the default for newly created VMs.</para> + </listitem> + + <listitem> + <para>Guest Control: Implemented initial support for automatic updating + of Guest Additions for Linux guests</para> + </listitem> + + <listitem> + <para>Guest Control: Implemented ability to wait for and/or reboot the + guest when updating Guest Additions via VBoxManage</para> + </listitem> + + <listitem> + <para>VBoxManage: Added Guest Control "waitrunlevel" sub-command to + make it possible to wait for a guest to reach a certain run level</para> + </listitem> + + <listitem> + <para>Windows hosts: Added experimental support of running autostarted VMs + in session 0, to allow running VMS even when a usser is not being logged + in (disabled by default, please consult the manual)</para> + </listitem> + + <listitem> + <para>macOS host: Dropped all kernel extensions. VirtualBox relies fully on + the hypervisor and vmnet frameworks provided by Apple now. At the moment + the implementation lacks "Internal Networking" functionality. This will be + provided at a later date.</para> + </listitem> + + <listitem> + <para>macOS host: Providing a Developer Preview package for systems with + an Apple silicon CPU. This is unsupported work in progress, and is known + to have very modest performance.</para> + </listitem> + + <listitem> + <para>Linux Guest Additions: Reworked guest screen re-size functionality, + added basic integration with some of guest Desktop Environments</para> + </listitem> + + <listitem> + <para>Devices: Implemented new 3D support based on DirectX 11 (and DXVK + on non Windows hosts)</para> + </listitem> + + <listitem> + <para>Devices: Added virtual IOMMU devices (Intel and AMD variant)</para> + </listitem> + + <listitem> + <para>Devices: Added virtual TPM 1.2 and 2.0 devices</para> + </listitem> + + <listitem> + <para>Devices: The EHCI and XHCI USB controller devices are now part of the + open source base package</para> + </listitem> + + <listitem> + <para>EFI: Added support for Secure Boot</para> + </listitem> + + <listitem> + <para>Debugging: Added experimental support for guest debugging through + GDB and highly experimental support for guest debugging through KD/WinDbg</para> + </listitem> + + </itemizedlist> + + <para>In addition, the following items were fixed and/or added:</para> + + <itemizedlist> + + <listitem> + <para>OCI: Cloud networking functionality is enhanced for local VMs, now local VMs could + be connected to cloud networking</para> + </listitem> + + <listitem> + <para>GUI: Improved behavior of the virtual machine list and various VM related tools in case + multiple items are selected</para> + </listitem> + + <listitem> + <para>GUI: On available platforms, added a new option to disable the host's screensaver</para> + </listitem> + + <listitem> + <para>GUI: Reworked global preferences, machine settings and the wizards to improve stability + and usability</para> + </listitem> + + <listitem> + <para>GUI: Improving mouse handling in multi-monitor case on X11 platform</para> + </listitem> + + <listitem> + <para>GUI: Medium enumeration engine was reworked to improve permormance</para> + </listitem> + + <listitem> + <para>GUI: NAT Network stuff was moved from global preferences to global Network Manager tool</para> + </listitem> + + <listitem> + <para>GUI: Extension Pack Manager was moved from global preferences to global tools</para> + </listitem> + + <listitem> + <para>GUI: Improved overall accessibility</para> + </listitem> + + <listitem> + <para>GUI: Migrating to recent Qt versions.</para> + </listitem> + + </itemizedlist> + </sect1> + +</chapter> diff --git a/doc/manual/xhtml-qhelp.xsl b/doc/manual/xhtml-qhelp.xsl new file mode 100644 index 00000000..07aee34d --- /dev/null +++ b/doc/manual/xhtml-qhelp.xsl @@ -0,0 +1,104 @@ +<?xml version="1.0"?> +<!-- + Copyright (C) 2020-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<xsl:stylesheet version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:xhtml="http://www.w3.org/1999/xhtml"> + <xsl:output method="xml" omit-xml-declaration="no"/> + <!-- Don't include non matching elements in output --> + <xsl:template match="text()"/> + <xsl:strip-space elements="*"/> + + <!-- maybe a bit nicer way of adding a new line to the output --> + <xsl:variable name="newline"><xsl:text> + </xsl:text></xsl:variable> + + <xsl:variable name="inputFileName"> + <xsl:text>UserManual.xhtml</xsl:text> + </xsl:variable> + + <xsl:template match="/"> + <xsl:element name="QtHelpProject"> + <xsl:attribute name="version"> + <xsl:value-of select="format-number(1, '.0')" /> + </xsl:attribute> + <xsl:value-of select="$newline" /> + <xsl:element name="namespace">org.virtualbox</xsl:element> + <xsl:value-of select="$newline" /> + <xsl:element name="virtualFolder">manual</xsl:element> + <xsl:value-of select="$newline" /> + <xsl:element name="filterSection"> + <xsl:value-of select="$newline" /> + <xsl:element name="toc"> + <xsl:apply-templates select="//xhtml:div[@class='toc']//xhtml:span[@class='chapter'] | //xhtml:div[@class='toc']//xhtml:span[@class='preface']"/> + </xsl:element><!-- toc --> + <xsl:value-of select="$newline" /> + <!-- <xsl:element name="keywords"></xsl:element> --> + <xsl:value-of select="$newline" /> + <xsl:element name="files"> + <!-- ======================input html file(s)============================= --> + <xsl:value-of select="$newline" /> + <!-- ====================chunked html input files========================== --> + <!-- Process div tag with class='toc'. For each space with class='chapter' --> + <!-- add a <file>ch(position()).html</file> assuming our docbook chunked html --> + <!-- files are named in this fashion. --> + <!-- <xsl:apply-templates select="//xhtml:div[@class='toc']//xhtml:span[@class='chapter']"/> --> + <!-- ====================single html input file========================== --> + <xsl:element name="file"> + <xsl:value-of select="$inputFileName" /> + </xsl:element> + <xsl:value-of select="$newline" /> + <!-- ===================================================================== --> + <!-- ===================image files======================================= --> + <xsl:apply-templates select="//xhtml:img"/> + <!-- ===================================================================== --> + + </xsl:element> + <xsl:value-of select="$newline" /> + </xsl:element> + <xsl:value-of select="$newline" /> + </xsl:element> + </xsl:template> + + <!-- ===================toc related template(s)====================== --> + <xsl:template match="xhtml:span[@class='chapter'] | xhtml:span[@class='preface']"> + <xsl:element name="section"> + <xsl:attribute name="title"> + <xsl:value-of select="*" /> + </xsl:attribute> + <xsl:attribute name="ref"> + <xsl:value-of select="$inputFileName" /><xsl:value-of select="xhtml:a/@href" /> + </xsl:attribute> + </xsl:element> + <xsl:value-of select="$newline" /> + </xsl:template> + <!-- ============================================================== --> + + <xsl:template match="//xhtml:img"> + <xsl:element name="file"> + <xsl:value-of select="@src"/> + </xsl:element> + <xsl:value-of select="$newline" /> + </xsl:template> + + +</xsl:stylesheet> diff --git a/doc/manual/xidl2docbook.xsl b/doc/manual/xidl2docbook.xsl new file mode 100644 index 00000000..67c6c0a4 --- /dev/null +++ b/doc/manual/xidl2docbook.xsl @@ -0,0 +1,588 @@ +<?xml version="1.0"?> + +<!-- + xidl2docbook.xsl: + XSLT stylesheet that generates docbook from + VirtualBox.xidl. +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<xsl:stylesheet + version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:exsl="http://exslt.org/common" + extension-element-prefixes="exsl"> + + <xsl:output + method="xml" + version="1.0" + encoding="utf-8" + indent="yes"/> + + <xsl:strip-space elements="*"/> + + <!-- - - - - - - - - - - - - - - - - - - - - - - + Keys for more efficiently looking up of types. + - - - - - - - - - - - - - - - - - - - - - - --> + +<xsl:key name="G_keyEnumsByName" match="//enum[@name]" use="@name"/> +<xsl:key name="G_keyInterfacesByName" match="//interface[@name]" use="@name"/> +<xsl:key name="G_keyResultsByName" match="//result[@name]" use="@name"/> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + global XSLT variables + - - - - - - - - - - - - - - - - - - - - - - --> + +<xsl:variable name="G_xsltFilename" select="'glue-jaxws.xsl'" /> + +<!-- collect all interfaces with "wsmap='suppress'" in a global variable for + quick lookup --> +<xsl:variable name="G_setSuppressedInterfaces" + select="//interface[@wsmap='suppress']" /> + +<xsl:template name="makeLinkId"> + <xsl:param name="ifname" /> + <xsl:param name="member" /> + <xsl:value-of select="concat($ifname, '__', $member)"/> +</xsl:template> + +<xsl:template name="emitType"> + <xsl:param name="type" /> + <xsl:choose> + <xsl:when test="$type"> + <xsl:choose> + <xsl:when test="count(key('G_keyInterfacesByName',$type)) > 0"> + <link> + <xsl:attribute name="linkend"> + <xsl:value-of select="translate($type, ':', '_')" /> + </xsl:attribute> + <xsl:value-of select="$type" /> + </link> + </xsl:when> + <xsl:when test="count(key('G_keyEnumsByName',$type)) > 0"> + <link> + <xsl:attribute name="linkend"> + <xsl:value-of select="translate($type, ':', '_')" /> + </xsl:attribute> + <xsl:value-of select="$type" /> + </link> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$type" /> + </xsl:otherwise> + </xsl:choose> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="'void'" /> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + +<xsl:template name="isWebserviceOnly"> + <xsl:for-each select="ancestor-or-self::*"> + <xsl:if test="(name()='if') and (@target='wsdl')"> + <xsl:text>yes</xsl:text> + </xsl:if> + </xsl:for-each> +</xsl:template> + + +<!-- - - - - - - - - - - - - - - - - - - - - - - + root match + - - - - - - - - - - - - - - - - - - - - - - --> + +<xsl:template match="/idl"> + <book> <!-- Need a single top-level element for xi:include, we'll skip it using xpointer. --> + <chapter id="sdkref_classes"> + <title>Classes (interfaces)</title> + <xsl:for-each select="//interface"> + <xsl:sort select="@name"/> + + <!-- ignore those interfaces within module sections; they don't have uuid --> + <xsl:if test="@uuid"> + <xsl:variable name="ifname" select="@name" /> + <xsl:variable name="wsmap" select="@wsmap" /> + <xsl:variable name="wscpp" select="@wscpp" /> + <xsl:variable name="wsonly"><xsl:call-template name="isWebserviceOnly" /></xsl:variable> + <xsl:variable name="extends" select="@extends" /> + <xsl:variable name="reportExtends" select="not($extends='$unknown') and not($extends='$errorinfo')" /> + + <sect1> + <xsl:attribute name="id"> + <xsl:value-of select="$ifname" /> + </xsl:attribute> + <title><xsl:value-of select="$ifname" /> + <xsl:if test="$reportExtends"> + <xsl:value-of select="concat(' (', @extends, ')')" /> + </xsl:if> + </title> + + <xsl:choose> + <xsl:when test="$wsmap='suppress'"> + <para><note><para> + This interface is not supported in the web service. + </para></note></para> + </xsl:when> + <xsl:when test="$wsmap='struct'"> + <para><note><para>With the web service, this interface is mapped to a structure. Attributes that return this interface will not return an object, but a complete structure + containing the attributes listed below as structure members.</para></note></para> + </xsl:when> + <xsl:when test="$wsonly='yes'"> + <para><note><para>This interface is supported in the web service only, not in COM/XPCOM.</para></note></para> + </xsl:when> + </xsl:choose> + + <xsl:if test="$reportExtends"> + <para><note><para> + This interface extends + <link> + <xsl:attribute name="linkend"><xsl:value-of select="$extends" /></xsl:attribute> + <xsl:value-of select="$extends" /> + </link> + and therefore supports all its methods and attributes as well. + </para></note></para> + </xsl:if> + + <xsl:apply-templates select="desc" /> + + <xsl:if test="attribute"> + <sect2> + <title>Attributes</title> + <xsl:for-each select="attribute"> + <xsl:variable name="attrtype" select="@type" /> + <sect3> + <xsl:attribute name="id"> + <xsl:call-template name="makeLinkId"> + <xsl:with-param name="ifname" select="$ifname" /> + <xsl:with-param name="member" select="@name" /> + </xsl:call-template> + </xsl:attribute> + <title> + <xsl:choose> + <xsl:when test="@readonly='yes'"> + <xsl:value-of select="concat(@name, ' (read-only)')" /> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="concat(@name, ' (read/write)')" /> + </xsl:otherwise> + </xsl:choose> + </title> + <programlisting> + <xsl:call-template name="emitType"> + <xsl:with-param name="type" select="$attrtype" /> + </xsl:call-template> + <xsl:value-of select="concat(' ', $ifname, '::', @name)" /> + <xsl:if test="(@array='yes') or (@safearray='yes')"> + <xsl:text>[]</xsl:text> + </xsl:if> + </programlisting> + <xsl:if test="( ($attrtype=($G_setSuppressedInterfaces/@name)) )"> + <para><note><para> + This attribute is not supported in the web service. + </para></note></para> + </xsl:if> + <xsl:apply-templates select="desc" /> + </sect3> + </xsl:for-each> + </sect2> + </xsl:if> + + <xsl:if test="method"> +<!-- <sect2> --> +<!-- <title>Methods</title> --> + <xsl:for-each select="method"> + <xsl:sort select="@name" /> + <xsl:variable name="returnidltype" select="param[@dir='return']/@type" /> + <sect2> + <xsl:attribute name="id"> + <xsl:call-template name="makeLinkId"> + <xsl:with-param name="ifname" select="$ifname" /> + <xsl:with-param name="member" select="@name" /> + </xsl:call-template> + </xsl:attribute> + <title> + <xsl:value-of select="@name" /> + </title> + <xsl:if test=" (param[@type=($G_setSuppressedInterfaces/@name)]) + or (param[@mod='ptr'])" > + <para><note><para> + This method is not supported in the web service. + </para></note></para> + </xsl:if> + <!-- make a set of all parameters with in and out direction --> + <xsl:variable name="paramsinout" select="param[@dir='in' or @dir='out']" /> + <programlisting> + <!--emit return type--> + <xsl:call-template name="emitType"> + <xsl:with-param name="type" select="$returnidltype" /> + </xsl:call-template> + <xsl:if test="(param[@dir='return']/@array='yes') or (param[@dir='return']/@safearray='yes')"> + <xsl:text>[]</xsl:text> + </xsl:if> + <xsl:value-of select="concat(' ', $ifname, '::', @name, '(')" /> + <xsl:if test="$paramsinout"> + <xsl:for-each select="$paramsinout"> + <xsl:text> </xsl:text> + <xsl:value-of select="concat(' [', @dir, '] ')" /> + <xsl:if test="@mod = 'ptr'"> + <xsl:text>[ptr] </xsl:text> + </xsl:if> + <xsl:call-template name="emitType"> + <xsl:with-param name="type" select="@type" /> + </xsl:call-template> + <emphasis role="bold"> + <xsl:value-of select="concat(' ', @name)" /> + </emphasis> + <xsl:if test="(@array='yes') or (@safearray='yes')"> + <xsl:text>[]</xsl:text> + </xsl:if> + <xsl:if test="not(position()=last())"> + <xsl:text>, </xsl:text> + </xsl:if> + </xsl:for-each> + </xsl:if> + <xsl:text>)</xsl:text> + </programlisting> + + <xsl:if test="$paramsinout"> + <glosslist> + <xsl:for-each select="$paramsinout"> + <glossentry> + <glossterm> + <xsl:value-of select="@name" /> + </glossterm> + <glossdef> + <xsl:if test="not(desc)"> + <para/> + </xsl:if> + <xsl:apply-templates select="desc" /> + </glossdef> + </glossentry> + </xsl:for-each> + </glosslist> + </xsl:if> + + <!-- dump the description here --> + <xsl:apply-templates select="desc" /> + + <xsl:if test="desc/result"> + <para>If this method fails, the following error codes may be reported:</para> + <itemizedlist> + <xsl:for-each select="desc/result"> + <listitem> + <para><code><xsl:value-of select="@name" />: </code> + <xsl:apply-templates /> + </para> + </listitem> + </xsl:for-each> + </itemizedlist> + </xsl:if> + </sect2> + </xsl:for-each> +<!-- </sect2> --> + </xsl:if> + + </sect1> + </xsl:if> + </xsl:for-each> + </chapter> + + <chapter id="sdkref_enums"> + <title>Enumerations (enums)</title> + <xsl:for-each select="//enum"> + <xsl:sort select="@name"/> + + <xsl:variable name="ifname" select="@name" /> + <xsl:variable name="wsmap" select="@wsmap" /> + <xsl:variable name="wscpp" select="@wscpp" /> + + <sect1> + <xsl:attribute name="id"> + <xsl:value-of select="$ifname" /> + </xsl:attribute> + <title><xsl:value-of select="$ifname" /></title> + + <xsl:apply-templates select="desc" /> + + <glosslist> + <xsl:for-each select="const"> + <glossentry> + <glossterm> + <xsl:attribute name="id"> + <xsl:call-template name="makeLinkId"> + <xsl:with-param name="ifname" select="$ifname" /> + <xsl:with-param name="member" select="@name" /> + </xsl:call-template> + </xsl:attribute> + <xsl:value-of select="@name" /> + </glossterm> + <glossdef> + <xsl:if test="not(desc)"> + <para/> + </xsl:if> + <xsl:apply-templates select="desc" /> + </glossdef> + </glossentry> + </xsl:for-each> + </glosslist> + </sect1> + </xsl:for-each> + </chapter> + </book> +</xsl:template> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + if + - - - - - - - - - - - - - - - - - - - - - - --> + +<!-- + * ignore all |if|s except those for WSDL target +--> +<xsl:template match="if"> + <xsl:if test="@target='wsdl'"> + <xsl:apply-templates/> + </xsl:if> +</xsl:template> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + cpp + - - - - - - - - - - - - - - - - - - - - - - --> + +<xsl:template match="cpp"> +<!-- ignore this --> +</xsl:template> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + result + - - - - - - - - - - - - - - - - - - - - - - --> + +<xsl:template match="result"> + <!-- ignore this, we handle them explicitly in method loops --> +</xsl:template> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + library + - - - - - - - - - - - - - - - - - - - - - - --> + +<xsl:template match="library"> + <xsl:apply-templates /> +</xsl:template> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + class + - - - - - - - - - - - - - - - - - - - - - - --> + +<xsl:template match="module/class"> +<!-- TODO swallow for now --> +</xsl:template> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + enum + - - - - - - - - - - - - - - - - - - - - - - --> + +<xsl:template match="enum"> +</xsl:template> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + const + - - - - - - - - - - - - - - - - - - - - - - --> + +<!-- +<xsl:template match="const"> + <xsl:apply-templates /> +</xsl:template> +--> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + desc + - - - - - - - - - - - - - - - - - - - - - - --> + +<xsl:template match="desc"> + <!-- todo: wrapping the entire content in a single para is actually not + entirely correct, as it contains empty lines denoting new paragraphs --> + <para> + <xsl:apply-templates /> + </para> +</xsl:template> + +<xsl:template name="getCurrentInterface"> + <xsl:for-each select="ancestor-or-self::*"> + <xsl:if test="name()='interface'"> + <xsl:value-of select="@name"/> + </xsl:if> + </xsl:for-each> +</xsl:template> + +<!-- <link to="DeviceType::HardDisk"/> --> +<xsl:template match="link"> + <link> + <xsl:variable name="tmp" select="@to" /> + <xsl:variable name="enumNameFromCombinedName"> + <xsl:value-of select="substring-before($tmp, '_')" /> + </xsl:variable> + <xsl:variable name="enumValueFromCombinedName"> + <xsl:value-of select="substring-after($tmp, '_')" /> + </xsl:variable> + <xsl:choose> + <xsl:when test="count(key('G_keyInterfacesByName',$tmp)) > 0 or count(key('G_keyEnumsByName',$tmp)) > 0"><!-- link to interface only --> + <xsl:attribute name="linkend"><xsl:value-of select="@to" /></xsl:attribute> + <xsl:value-of select="$tmp" /> + </xsl:when> + <xsl:when test="count(key('G_keyEnumsByName',$enumNameFromCombinedName)) > 0"> + <xsl:attribute name="linkend"> + <xsl:value-of select="concat($enumNameFromCombinedName, '__', $enumValueFromCombinedName)" /> + </xsl:attribute> + <xsl:value-of select="$enumValueFromCombinedName" /> + </xsl:when> + <xsl:otherwise> + <xsl:variable name="currentif"> + <xsl:call-template name="getCurrentInterface" /> + </xsl:variable> + <xsl:variable name="if"><!-- interface --> + <xsl:choose> + <xsl:when test="contains(@to, '#')"> + <xsl:value-of select="$currentif" /> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="substring-before(@to, '::')" /> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:variable name="member"><!-- member in that interface --> + <xsl:choose> + <xsl:when test="contains(@to, '#')"> + <xsl:value-of select="substring-after(@to, '#')" /> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="substring-after(@to, '::')" /> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + + <xsl:attribute name="linkend"><xsl:value-of select="concat($if, '__', $member)" /></xsl:attribute> + <xsl:variable name="autotextsuffix"> + <xsl:choose> + <!-- if link points to a method, append "()" --> + <xsl:when test="key('G_keyInterfacesByName',$if)/method[@name=$member]"> + <xsl:value-of select="'()'" /> + </xsl:when> + <!-- if link points to a safearray attribute, append "[]" --> + <xsl:when test="key('G_keyInterfacesByName',$if)/attribute[@name=$member]/@safearray = 'yes'"> + <xsl:value-of select="'[]'" /> + </xsl:when> + <xsl:when test="key('G_keyInterfacesByName',$if)/attribute[@name=$member]"/> + <xsl:when test="key('G_keyEnumsByName',$if)/const[@name=$member]"/> + <xsl:when test="count(key('G_keyResultsByName',$tmp)) > 0"/> + <xsl:otherwise> + <xsl:message terminate="yes"> + <xsl:value-of select="concat('Invalid link pointing to "', $tmp, '"')" /> + </xsl:message> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:choose> + <xsl:when test="./text()"><!-- link text given in source --> + <xsl:apply-templates /> + </xsl:when> + <xsl:when test="$if=$currentif"><!-- "near" link to method or attribute in current interface --> + <xsl:value-of select="concat($member, $autotextsuffix)" /> + </xsl:when> + <xsl:otherwise><!-- "far" link to other method or attribute --> + <xsl:value-of select="concat($if, '::', $member, $autotextsuffix)" /> + </xsl:otherwise> + </xsl:choose> + </xsl:otherwise> + </xsl:choose> + </link> +</xsl:template> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + note + - - - - - - - - - - - - - - - - - - - - - - --> + +<xsl:template match="note"> + <xsl:if test="not(@internal='yes')"> + <note><para> + <xsl:apply-templates /> + </para></note> + </xsl:if> +</xsl:template> + +<xsl:template match="tt"> + <computeroutput> + <xsl:apply-templates /> + </computeroutput> +</xsl:template> + +<xsl:template match="b"> + <emphasis role="bold"> + <xsl:apply-templates /> + </emphasis> +</xsl:template> + +<xsl:template match="i"> + <emphasis> + <xsl:apply-templates /> + </emphasis> +</xsl:template> + +<xsl:template match="see"> + <xsl:text>See also: </xsl:text> + <xsl:apply-templates /> +</xsl:template> + +<xsl:template match="ul"> + <itemizedlist> + <xsl:apply-templates /> + </itemizedlist> +</xsl:template> + +<xsl:template match="ol"> + <orderedlist> + <xsl:apply-templates /> + </orderedlist> +</xsl:template> + +<xsl:template match="li"> + <listitem> + <para> + <xsl:apply-templates /> + </para> + </listitem> +</xsl:template> + +<xsl:template match="h3"> + <emphasis role="bold"> + <xsl:apply-templates /> + </emphasis> +</xsl:template> + +<xsl:template match="pre"> + <screen><xsl:apply-templates /></screen> +</xsl:template> + +<xsl:template match="table"> + <xsl:apply-templates /> <!-- todo --> +</xsl:template> + +</xsl:stylesheet> diff --git a/doc/manual/xml2tag.xsl b/doc/manual/xml2tag.xsl new file mode 100644 index 00000000..da846b4a --- /dev/null +++ b/doc/manual/xml2tag.xsl @@ -0,0 +1,43 @@ +<?xml version="1.0"?> + +<!-- + xml2tag.xsl: + XSLT stylesheet that extracts just the tags of an XML document. +--> +<!-- + Copyright (C) 2018-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + 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, in version 3 of the + License. + + 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, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<xsl:stylesheet + version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> + + <xsl:output method="text"/> + + <xsl:strip-space elements="*"/> + + <xsl:template match="*"> + <xsl:value-of select="name()"/> + <xsl:text> </xsl:text> + <xsl:apply-templates select="*"/> + </xsl:template> + +</xsl:stylesheet> diff --git a/doc/technical/Resizing.wiki b/doc/technical/Resizing.wiki new file mode 100644 index 00000000..b6245ba3 --- /dev/null +++ b/doc/technical/Resizing.wiki @@ -0,0 +1,27 @@ +Please feel free to send documentation patches to the vbox-dev [https://www.virtualbox.org/wiki/Mailing_lists mailing list]. + += Mechanics of host-guest dynamic resizing = + +In normal use, with the standard graphical user interface and with Guest Additions installed, !VirtualBox resizes guest desktops to match whenever the host window is resized. This document describes the way the mechanism is supposed to - and usually does - work. It also points out the tricky parts which might potentially fail. + +== The guest video device == + +!VirtualBox virtual machines contain an emulated graphics card which can currently support up to 64 monitor outputs (the actual number is set by the user before starting the machine). Each output can be set to any resolution which the configured video RAM size will support (potentially using overlapping video RAM areas). Normally it will be controlled by the Guest Additions video driver or the Linux VMSVGA driver, but it can also be controlled by a VGA driver or using the VESA BIOS, which can only set a limit set of the resolutions that the card can handle, and only on the first screen. When the guest sets a new resolution on a given monitor output the user interface resizes the matching window to fit. This only happens once for each resolution change. If it appears to be repeating, the guest has probably got stuck setting and resetting resolutions. + +== Resizing triggered by the host == + +Virtual machines typically display into windows on the host computer, so it is convenient if the guest operating system can be told to adjust its display to fit well into the windows. This is done by simulating monitors with preferred resolutions of the host window sizes, and simulating monitor re-plugs when the host windows are resized. There are currently two ways that the guest can read the monitor size, depending on its driver and helper set-up. The VBox(S)VGA device gives the guest the information directly, whereas when the VMSVGA device is in use a helper has to read the monitor information from the so-called VMM (virtual machine monitor) device and tell the driver. There is no guarantee that the guest will actually use the preferred size, but it usually does. + +In Linux guests, the VBox(S)VGA drivers generate a random monitor serial number each time the size changes, because those guests remember monitors by serial number and may set a different resolution if a monitor they have seen before is connected. (There is a good reason for this on a physical computer of course, but we do not want it in our virtual ones.) The serial number trick does not work with VMSVGA, which can cause resizing to fail. Deleting the file ~/config/Monitors.xml in the guest helps. Another known problem is that on older Linux guests without kernel graphics drivers we send an ACPI monitor change notification, which a few older guests interpret as a request to cycle to the next available resolution after the resize has already taken place. No modern Linux system is known to be affected, and as of X.Org Server 1.19 in the guest we require use of the kernel driver. + +Legacy drivers, including the ones in the BIOS and EFI, are not able to read the preferred size. That should be fixable, but no one has yet found time to do it. Once the guest loads a more capable driver it reads the last preferred size requested by the host and adjusts to that (this currently does not work as expected with the Windows drivers, but should be fixed soon). + +== Guest Additions components == +=== Windows guests === + * VBoxVideo: the main graphics driver loaded into the kernel. It can tell how many screens (that is, screen connectors) the guest currently supports, and can enable and disable them as well as setting resolutions to them. It reports this information to Windows on the guest. It can not receive information from the host about screen changes (mode hints, monitor unplug or hotplug) itself, but provides an interface for a user-space tool which can to provide that information. It remembers information received in the Windows registry and simply assumes when it loads that the configuration has not changed since it was last used. + * VBoxTray: a user-space daemon which is loaded when a user logs into Windows on the guest and runs as part of that session. It can receive screen change information from the host and forward it to VBoxVideo. It also handles seamless mode and other unrelated guest functionality. + +=== X.Org/Wayland guests === + * vboxvideo.ko: the main graphics driver loaded into the kernel, currently Linux-only (3.11 and later). It is known to be supported by X.Org Server 1.17 and later and by GNOME Shell/Wayland as of at least Fedora 25. It can receive information from the host about screen changes (mode hints, monitor unplug or hotplug) itself, though it depends on user-space to handle that. All half-recent GNOME Shell versions (X.Org and Wayland), Ubuntu Unity versions and KDE versions do that. + * VBoxClient: a user-space daemon which is loaded when a user logs into X.Org on the guest. It is loaded by the desktop environment and works with most known ones. For desktop environments which cannot handle screen changes themselves it does that for them (it waits two seconds before responding to the change to give the environment a chance to respond itself, rather than trying to guess which can and which can't). It cannot do this before log-in of course. It also handles seamless mode and other unrelated guest functionality. + * vboxvideo_drv.so: the main graphics driver, but a different version which runs inside X.Org/XFree86 in user-space. It cannot co-exist with vboxvideo.ko, but does roughly the same job. It is supported up to X.Org Server 1.18. So X.Org 1.19 and later cannot be used with Linux 3.10 and earlier except with fall-back graphics. This is not expected to be a problem. |
