VirtualBox

source: vbox/trunk/doc/manual/en_US/man_VBoxManage-encryptmedium.xml@ 103068

Last change on this file since 103068 was 99513, checked in by vboxsync, 20 months ago

manual,VBoxManage,isomaker/viso: Require all refsect1 and refsect2 elements to have @id attributes in manpages (refentry) to make these predictable and the split up topic files easier to handle for the docs team. Also requires these @id values to start with the refentry @id + '-'. Corrected a few bogus ones. Because 'controlvm' has too many sub-commands, HELP_SCOPE_ IDs will not be generated for 'See Also' and 'Examples' sections. bugref:10302

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 7.2 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!--
3 manpage, user manual, usage: VBoxManage encryptmedium
4-->
5<!--
6 Copyright (C) 2006-2023 Oracle and/or its affiliates.
7
8 This file is part of VirtualBox base platform packages, as
9 available from https://www.virtualbox.org.
10
11 This program is free software; you can redistribute it and/or
12 modify it under the terms of the GNU General Public License
13 as published by the Free Software Foundation, in version 3 of the
14 License.
15
16 This program is distributed in the hope that it will be useful, but
17 WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 General Public License for more details.
20
21 You should have received a copy of the GNU General Public License
22 along with this program; if not, see <https://www.gnu.org/licenses>.
23
24 SPDX-License-Identifier: GPL-3.0-only
25-->
26<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
27 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
28<!ENTITY % all.entities SYSTEM "all-entities.ent">
29%all.entities;
30]>
31<refentry id="vboxmanage-encryptmedium" lang="en">
32 <refentryinfo>
33 <pubdate>$Date: 2023-04-21 21:59:02 +0000 (Fri, 21 Apr 2023) $</pubdate>
34 <title>VBoxManage encryptmedium</title>
35 </refentryinfo>
36
37 <refmeta>
38 <refentrytitle>VBoxManage-encryptmedium</refentrytitle>
39 <manvolnum>1</manvolnum>
40 </refmeta>
41
42 <refnamediv>
43 <refname>VBoxManage-encryptmedium</refname>
44 <refpurpose>manage a DEK-encrypted medium or image</refpurpose>
45 <refclass>&product-name;</refclass>
46 </refnamediv>
47
48 <refsynopsisdiv>
49 <cmdsynopsis id="synopsis-vboxmanage-encryptmedium">
50<!-- The 'id' is mandatory and must start with 'synopsis-'. -->
51 <command>VBoxManage encryptmedium</command>
52 <group choice="req">
53 <arg choice="plain"><replaceable>uuid</replaceable></arg>
54 <arg choice="plain"><replaceable>filename</replaceable></arg>
55 </group>
56 <arg>--cipher=<replaceable>cipher-ID</replaceable></arg>
57 <arg>--newpassword=<replaceable>password</replaceable></arg>
58 <arg>--newpasswordid=<replaceable>password-ID</replaceable></arg>
59 <arg>--oldpassword=<replaceable>password</replaceable></arg>
60 </cmdsynopsis>
61 </refsynopsisdiv>
62
63 <refsect1 id="vboxmanage-encryptmedium-description">
64 <title>Description</title>
65 <para>
66 The <command>VBoxManage encryptmedium</command> command enables
67 you to create and manage a DEK-encrypted medium or image. You can
68 encrypt an image, decrypt an image, and change the encryption
69 password of an image. See
70 <xref linkend="diskencryption-encryption" />.
71 </para>
72 <variablelist>
73 <varlistentry>
74 <term><replaceable>uuid</replaceable> | <replaceable>filename</replaceable></term>
75 <listitem><para>
76 Specifies the Universally Unique Identifier (UUID) or the
77 absolute path name of the medium or image to encrypt.
78 </para></listitem>
79 </varlistentry>
80 <varlistentry>
81 <term><option>--newpassword=<replaceable>password</replaceable></option></term>
82 <listitem><para>
83 Specifies the new encryption password.
84 <replaceable>password</replaceable> is either the absolute
85 path name of a password file on the host operating system or
86 <literal>-</literal>, which prompts you for the password.
87 </para><para>
88 You must use the <option>--newpasswordid</option> option
89 with this <option>--newpassword</option> option.
90 </para></listitem>
91 </varlistentry>
92 <varlistentry>
93 <term><option>--oldpassword=<replaceable>password</replaceable></option></term>
94 <listitem><para>
95 Specifies the original encryption password.
96 <replaceable>password</replaceable> is either the absolute
97 path name of a password file on the host operating system or
98 <literal>-</literal>, which prompts you for the original
99 password.
100 </para><para>
101 This option enables you to gain access to an encrypted
102 medium or image to do the following:
103 </para><itemizedlist>
104 <listitem><para>
105 Decrypt an encrypted image by using this option by
106 itself.
107 </para></listitem>
108 <listitem><para>
109 Change the password of the encrypted image by using the
110 <option>--newpassword</option> option.
111 </para></listitem>
112 <listitem><para>
113 Change the encryption cipher of the image by using the
114 <option>--cipher</option> option.
115 </para></listitem>
116 </itemizedlist></listitem>
117 </varlistentry>
118 <varlistentry>
119 <term><option>--cipher=<replaceable>cipher-ID</replaceable></option></term>
120 <listitem><para>
121 Specifies the cipher to use for encryption. Valid values are
122 <literal>AES-XTS128-PLAIN64</literal> or
123 <literal>AES-XTS256-PLAIN64</literal>.
124 </para><para>
125 This option enables you to set up or change encryption on
126 the medium or image.
127 </para></listitem>
128 </varlistentry>
129 <varlistentry>
130 <term><option>--newpasswordid=<replaceable>password-ID</replaceable></option></term>
131 <listitem><para>
132 Specifies a new password identifier that is used for correct
133 identification when supplying multiple passwords during VM
134 startup.
135 </para><para>
136 If you use the same password and password identifier when
137 encrypting multiple images, you need to supply the password
138 only one time during VM startup.
139 </para></listitem>
140 </varlistentry>
141 </variablelist>
142 </refsect1>
143
144 <refsect1 id="vboxmanage-encryptmedium-examples">
145 <title>Examples</title>
146 <remark role="help-scope" condition="GLOBAL"/>
147 <para>
148 The following example shows how to encrypt the
149 <filename>ol7u4-1.vdi</filename> image by using the
150 <literal>AES-XTS128-PLAIN64</literal> cipher, specifying a
151 password identifier of <literal>1001</literal>, and using the
152 <filename>$HOME/pwfile</filename> password file:
153 </para>
154<screen>$ VBoxManage encryptmedium "$HOME/VirtualBox VMs/ol7u4/ol7u4-1.vdi" \
155 --cipher="AES-XTS128-PLAIN64" --newpasswordid="1001" --newpassword=$HOME/pwfile</screen>
156 <para>
157 The following example shows how to decrypt an encrypted image
158 called <filename>ol7u4-2.vdi</filename>:
159 </para>
160<screen>$ VBoxManage encryptmedium "$HOME/VirtualBox VMs/ol7u4/ol7u4-2.vdi" \
161 --oldpassword=-
162 Password: <replaceable>original-password</replaceable></screen>
163 <para>
164 The following example shows how to change the password for an
165 encrypted image called <filename>ol7u4-3.vdi</filename>. The
166 command reads the original password from the
167 <filename>$HOME/pwfile.orig</filename> file, reads the new
168 password from the <filename>$HOME/pwfile</filename> file, and
169 assigns a password identifier of <literal>1001</literal>.
170 </para>
171<screen>$ VBoxManage encryptmedium "$HOME/VirtualBox VMs/ol7u4/ol7u4-3.vdi" \
172 --oldpassword=$HOME/pwfile.orig --newpassword=$HOME/pwfile --newpasswordid="1001"</screen>
173 </refsect1>
174</refentry>
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette