VirtualBox

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

Last change on this file since 103068 was 99513, checked in by vboxsync, 19 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: 23.6 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!--
3 manpage, user manual, usage: VBoxManage storageattach
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-storageattach" lang="en">
32 <refentryinfo>
33 <pubdate>August 2019</pubdate>
34 <title>VBoxManage storageattach</title>
35 </refentryinfo>
36
37 <refmeta>
38 <refentrytitle>VBoxManage-storageattach</refentrytitle>
39 <manvolnum>1</manvolnum>
40 </refmeta>
41
42 <refnamediv>
43 <refname>VBoxManage-storageattach</refname>
44 <refpurpose>attach, remove, and modify storage media used by a virtual machine</refpurpose>
45 <refclass>&product-name;</refclass>
46 </refnamediv>
47
48 <refsynopsisdiv>
49 <cmdsynopsis id="synopsis-vboxmanage-storageattach">
50<!-- The 'id' is mandatory and must start with 'synopsis-'. -->
51 <command>VBoxManage storageattach</command>
52 <group choice="req">
53 <arg choice="plain"><replaceable>uuid</replaceable></arg>
54 <arg choice="plain"><replaceable>vmname</replaceable></arg>
55 </group>
56 <arg choice="req">--storagectl=<replaceable>name</replaceable></arg>
57 <arg>--bandwidthgroup=<group choice="plain">
58 <arg choice="plain">name</arg>
59 <arg choice="plain">none</arg>
60 </group></arg>
61 <arg>--comment=<replaceable>text</replaceable></arg>
62 <arg>--device=<replaceable>number</replaceable></arg>
63 <arg>--discard=<group choice="plain">
64 <arg choice="plain">on</arg>
65 <arg choice="plain">off</arg>
66 </group></arg>
67 <arg>--encodedlun=<replaceable>lun</replaceable></arg>
68 <arg>--forceunmount</arg>
69 <arg>--hotpluggable=<group choice="plain">
70 <arg choice="plain">on</arg>
71 <arg choice="plain">off</arg>
72 </group></arg>
73 <arg>--initiator=<replaceable>initiator</replaceable></arg>
74 <arg>--intnet</arg>
75 <arg>--lun=<replaceable>lun</replaceable></arg>
76 <arg>--medium=<group choice="plain">
77 <arg choice="plain">none</arg>
78 <arg choice="plain">emptydrive</arg>
79 <arg choice="plain">additions</arg>
80 <arg choice="plain"><replaceable>uuid</replaceable></arg>
81 <arg choice="plain"><replaceable>filename</replaceable></arg>
82 <arg choice="plain">host:<replaceable>drive</replaceable></arg>
83 <arg choice="plain">iscsi</arg>
84 </group></arg>
85 <arg>--mtype=<group choice="plain">
86 <arg choice="plain">normal</arg>
87 <arg choice="plain">writethrough</arg>
88 <arg choice="plain">immutable</arg>
89 <arg choice="plain">shareable</arg>
90 <arg choice="plain">readonly</arg>
91 <arg choice="plain">multiattach</arg>
92 </group></arg>
93 <arg>--nonrotational=<group choice="plain">
94 <arg choice="plain">on</arg>
95 <arg choice="plain">off</arg>
96 </group></arg>
97 <arg>--passthrough=<group choice="plain">
98 <arg choice="plain">on</arg>
99 <arg choice="plain">off</arg>
100 </group></arg>
101 <arg>--passwordfile=<replaceable>file</replaceable></arg>
102 <arg>--password=<replaceable>password</replaceable></arg>
103 <arg>--port=<replaceable>number</replaceable></arg>
104 <arg>--server=<group choice="plain">
105 <arg choice="plain"><replaceable>name</replaceable></arg>
106 <arg choice="plain"><replaceable>ip</replaceable></arg>
107 </group></arg>
108 <arg>--setparentuuid=<replaceable>uuid</replaceable></arg>
109 <arg>--setuuid=<replaceable>uuid</replaceable></arg>
110 <arg>--target=<replaceable>target</replaceable></arg>
111 <arg>--tempeject=<group choice="plain">
112 <arg choice="plain">on</arg>
113 <arg choice="plain">off</arg>
114 </group></arg>
115 <arg>--tport=<replaceable>port</replaceable></arg>
116 <arg>--type=<group choice="plain">
117 <arg choice="plain">dvddrive</arg>
118 <arg choice="plain">fdd</arg>
119 <arg choice="plain">hdd</arg>
120 </group></arg>
121 <arg>--username=<replaceable>username</replaceable></arg>
122 </cmdsynopsis>
123 </refsynopsisdiv>
124
125 <refsect1 id="vboxmanage-storageattach-description">
126 <title>Description</title>
127 <para>
128 The <command>VBoxManage storageattach</command> command enables
129 you to manage a storage medium that you connected to a storage
130 controller by using the <command>VBoxManage storagectl</command>
131 command.
132 </para>
133 <variablelist>
134 <varlistentry>
135 <term><option><replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></option></term>
136 <listitem><para>
137 Specifies the Universally Unique Identifier (UUID) or the
138 name of the virtual machine (VM).
139 </para></listitem>
140 </varlistentry>
141 <varlistentry>
142 <term><option>--storagectl=<replaceable>name</replaceable></option></term>
143 <listitem><para>
144 Specifies the name of the storage controller. Use the
145 <command>VBoxManage showvminfo</command> command to list the
146 storage controllers that are attached to the VM.
147 </para></listitem>
148 </varlistentry>
149 <varlistentry>
150 <term><option>--port=<replaceable>number</replaceable></option></term>
151 <listitem><para>
152 Specifies the port number of the storage controller to
153 modify. You must specify this option unless the storage
154 controller has only a single port.
155 </para></listitem>
156 </varlistentry>
157 <varlistentry>
158 <term><option>--device=<replaceable>number</replaceable></option></term>
159 <listitem><para>
160 Specifies the port's device number to modify. You must
161 specify this option unless the storage controller has only
162 one device per port.
163 </para></listitem>
164 </varlistentry>
165 <varlistentry>
166 <term><option>--type=dvddrive | fdd | hdd</option></term>
167 <listitem><para>
168 Specifies the drive type to which the medium is associated.
169 Only omit this option if the medium type can be determined
170 by using the <option>--medium</option> option or by
171 information provided by an earlier medium attachment
172 command.
173 </para></listitem>
174 </varlistentry>
175 <varlistentry>
176 <term><option>--medium=none | emptydrive | additions | <replaceable>uuid</replaceable> | <replaceable>filename</replaceable> | host:<replaceable>drive</replaceable> | iscsi</option></term>
177 <listitem><para>
178 Specifies one of the following values:
179 </para><variablelist>
180 <varlistentry>
181 <term><literal>none</literal></term>
182 <listitem><para>
183 Removes any existing device from the specified slot.
184 </para></listitem>
185 </varlistentry>
186 <varlistentry>
187 <term><literal>emptydrive</literal></term>
188 <listitem><para>
189 For a virtual DVD or floppy drive only.
190 </para><para>
191 Makes the device slot behave like a removeable drive
192 into which no media has been inserted.
193 </para></listitem>
194 </varlistentry>
195 <varlistentry>
196 <term><literal>additions</literal></term>
197 <listitem><para>
198 For a virtual DVD drive only.
199 </para><para>
200 Attaches the VirtualBox Guest Additions image to the
201 specified device slot.
202 </para></listitem>
203 </varlistentry>
204 <varlistentry>
205 <term><replaceable>uuid</replaceable></term>
206 <listitem><para>
207 Specifies the UUID of a storage medium to attach to
208 the specified device slot. The storage medium must
209 already be known to &product-name;, such as a storage
210 medium that is attached to another VM. Use the
211 <command>VBoxManage list</command> command to list
212 media.
213 </para></listitem>
214 </varlistentry>
215 <varlistentry>
216 <term><replaceable>filename</replaceable></term>
217 <listitem><para>
218 Specifies the full path of an existing disk image to
219 attach to the specified device slot. The disk image
220 can be in ISO, RAW, VDI, VMDK, or other format.
221 </para></listitem>
222 </varlistentry>
223 <varlistentry>
224 <term><literal>host:<replaceable>drive</replaceable></literal></term>
225 <listitem><para>
226 For a virtual DVD or floppy drive only.
227 </para><para>
228 Connects the specified device slot to the specified
229 DVD or floppy drive on the host computer.
230 </para></listitem>
231 </varlistentry>
232 <varlistentry>
233 <term><literal>iscsi</literal></term>
234 <listitem><para>
235 For virtual hard disks only.
236 </para><para>
237 Specifies an iSCSI target for which you must specify
238 additional information. See
239 <xref linkend="storage-iscsi" />.
240 </para></listitem>
241 </varlistentry>
242 </variablelist><para>
243 For removeable media such as floppies and DVDs, you can make
244 configuration changes while a VM is running. Changes to
245 devices or hard disk device slots require that the VM be
246 powered off.
247 </para></listitem>
248 </varlistentry>
249 <varlistentry>
250 <term><option>--mtype=normal | writethrough | immutable | shareable | readonly | multiattach</option></term>
251 <listitem><para>
252 Specifies how this medium behaves with respect to snapshots
253 and write operations. See <xref linkend="hdimagewrites" />.
254 </para></listitem>
255 </varlistentry>
256 <varlistentry>
257 <term><option>--comment=<replaceable>text</replaceable></option></term>
258 <listitem><para>
259 Specifies an optional description to store with the medium.
260 </para></listitem>
261 </varlistentry>
262 <varlistentry>
263 <term><option>--setuuid=<replaceable>uuid</replaceable></option></term>
264 <listitem><para>
265 Modifies the UUID of a medium before attaching it to a VM.
266 </para><para>
267 This is an expert option. Inappropriate values might make
268 the medium unusable or lead to broken VM configurations if
269 another VM already refers to the same medium.
270 </para><para>
271 Using the <option>--setuuid=""</option> option
272 assigns a new random UUID to an image, which can resolve
273 duplicate UUID errors if you used a file copy utility to
274 duplicate an image.
275 </para></listitem>
276 </varlistentry>
277 <varlistentry>
278 <term><option>--setparentuuid=<replaceable>uuid</replaceable></option></term>
279 <listitem><para>
280 Modifies the parent UUID of a medium before attaching it to
281 a VM.
282 </para><para>
283 This is an expert option. Inappropriate values might make
284 the medium unusable or lead to broken VM configurations if
285 another VM already refers to the same medium.
286 </para></listitem>
287 </varlistentry>
288 <varlistentry>
289 <term><option>--passthrough=on | off</option></term>
290 <listitem><para>
291 For a virtual DVD drive only.
292 </para><para>
293 Enables writing to a DVD. This feature is experimental, see
294 <xref linkend="storage-cds" />.
295 </para></listitem>
296 </varlistentry>
297 <varlistentry>
298 <term><option>--tempeject=on | off</option></term>
299 <listitem><para>
300 For a virtual DVD drive only.
301 </para><para>
302 Specifies whether to permit a temporary guest-triggered
303 medium eject operation. When set to <literal>on</literal>,
304 you can eject a medium. The ability for a guest-triggered
305 eject operation does not persist if the VM is powered off
306 and restarted. So, when you set this option to
307 <literal>on</literal> and the VM is restarted, the
308 originally configured medium is still in the drive.
309 </para></listitem>
310 </varlistentry>
311 <varlistentry>
312 <term><option>--nonrotational=on | off</option></term>
313 <listitem><para>
314 Enables you to specify that the virtual hard disk is
315 non-rotational. Some guest OSes, such as Windows 7 or later,
316 treat such disks as solid state drives (SSDs) and do not
317 perform disk fragmentation on them.
318 </para></listitem>
319 </varlistentry>
320 <varlistentry>
321 <term><option>--discard=on | off</option></term>
322 <listitem><para>
323 Specifies whether to enable the auto-discard feature for a
324 virtual hard disk. When set to <literal>on</literal>, a VDI
325 image is shrunk in response to a <command>trim</command>
326 command from the guest OS.
327 </para><para>
328 The virtual hard disk must meet the following requirements:
329 </para><itemizedlist>
330 <listitem><para>
331 The disk format must be VDI.
332 </para></listitem>
333 <listitem><para>
334 The size of the cleared area of the disk must be at
335 least 1 MB.
336 </para></listitem>
337 <listitem><para>
338 Ensure that the space being trimmed is at least a 1 MB
339 contiguous block at a 1 MB boundary.
340 </para></listitem>
341 </itemizedlist><para>
342 Consider running defragmentation commands as background cron
343 jobs to save space. On Windows, run the <command>defrag.exe
344 /D</command> command. On Linux, run the <command>btrfs
345 filesystem defrag</command> command.
346 </para><note>
347 <para>
348 When you configure the guest OS to issue the
349 <command>trim</command> command, the guest OS typically
350 sees the disk as an SSD.
351 </para>
352 <para>
353 Ext4 supports the <option>-o discard</option> mount
354 option. Mac OS X might require additional settings.
355 Windows 7, 8, and 10 automatically detect and support
356 SSDs. The Linux <command>exFAT</command> driver from
357 Samsung supports the <command>trim</command> command.
358 </para>
359 </note><para>
360 The Microsoft implementation of exFAT might not support this
361 feature.
362 </para><para>
363 You can use other methods to issue trim commands. The Linux
364 <command>fstrim</command> command is part of the
365 <filename>util-linux</filename> package. Earlier solutions
366 required you to zero out unused areas by using the
367 <command>zerofree</command> or a similar command, and then
368 to compact the disk. You can only perform these steps when
369 the VM is offline.
370 </para></listitem>
371 </varlistentry>
372 <varlistentry>
373 <term><option>--bandwidthgroup=<replaceable>name</replaceable></option></term>
374 <listitem><para>
375 Specifies the bandwidth group to use for the device. See
376 <xref linkend="storage-bandwidth-limit" />.
377 </para></listitem>
378 </varlistentry>
379 <varlistentry>
380 <term><option>--forceunmount</option></term>
381 <listitem><para>
382 For a virtual DVD or floppy drive only.
383 </para><para>
384 Forcibly unmounts the DVD, CD, or floppy or mounts a new
385 DVD, CD, or floppy even if the previous removable storage is
386 locked by the guest for reading. See
387 <xref linkend="storage-cds" />.
388 </para></listitem>
389 </varlistentry>
390 </variablelist>
391 <para>
392 The following options are applicable when you specify the
393 <option>--medium=iscsi</option> option:
394 </para>
395 <variablelist>
396 <varlistentry>
397 <term><option>--server=<replaceable>hostname</replaceable> | <replaceable>IP-address</replaceable></option></term>
398 <listitem><para>
399 Specifies the host name or IP address of the iSCSI target.
400 </para></listitem>
401 </varlistentry>
402 <varlistentry>
403 <term><option>--target=<replaceable>target</replaceable></option></term>
404 <listitem><para>
405 Specifies the target name string, which is determined by the
406 iSCSI target and is used to identify the storage resource.
407 </para></listitem>
408 </varlistentry>
409 <varlistentry>
410 <term><option>--tport=<replaceable>port</replaceable></option></term>
411 <listitem><para>
412 Specifies the TCP/IP port number of the iSCSI service on the
413 target.
414 </para></listitem>
415 </varlistentry>
416 <varlistentry>
417 <term><option>--lun=<replaceable>LUN</replaceable></option></term>
418 <listitem><para>
419 Specifies the logical unit number (LUN) of the target
420 resource. For a single disk drive, the value is zero.
421 </para></listitem>
422 </varlistentry>
423 <varlistentry>
424 <term><option>--encodedlun=<replaceable>LUN</replaceable></option></term>
425 <listitem><para>
426 Specifies the hexadecimal-encoded of the target resource.
427 For a single disk drive, the value is zero.
428 </para></listitem>
429 </varlistentry>
430 <varlistentry>
431 <term><option>--username=<replaceable>username</replaceable></option></term>
432 <listitem><para>
433 Specifies the user name to use for target authentication.
434 </para><note>
435 <para>
436 Unless you provide a settings password, the user name is
437 stored as clear text in the XML machine configuration
438 file.
439 </para>
440 </note></listitem>
441 </varlistentry>
442 <varlistentry>
443 <term><option>--password=<replaceable>password</replaceable></option></term>
444 <listitem><para>
445 Specifies the password used for target authentication.
446 </para><note>
447 <para>
448 Unless you provide a settings password, this password is
449 stored as clear text in the XML machine configuration
450 file. When you specify a settings password for the first
451 time, the target authentication password is stored in
452 encrypted form.
453 </para>
454 </note><remark>
455 This design does not conform to Oracle's security
456 guidelines. You should not be able to specify a password on
457 the command line because the password can be seen in a
458 process listing.
459 </remark></listitem>
460 </varlistentry>
461 <varlistentry>
462 <term><option>--passwordfile=<replaceable>password-filename</replaceable></option></term>
463 <listitem><para>
464 Specifies a file that contains the target authentication
465 password as clear text.
466 </para><note>
467 <para>
468 Use permission and ownership settings to ensure that the
469 contents of this file cannot be read by unauthorized
470 users.
471 </para>
472 </note></listitem>
473 </varlistentry>
474 <varlistentry>
475 <term><option>--initiator=<replaceable>initiator</replaceable></option></term>
476 <listitem><para>
477 Specifies the iSCSI initiator.
478 </para><para>
479 The Microsoft iSCSI Initiator is a system, such as a server,
480 that attaches to an IP network and initiates requests and
481 receives responses from an iSCSI target. The SAN components
482 in the iSCSI initiator are largely analogous to Fibre
483 Channel SAN components, and they include the following:
484 </para><itemizedlist>
485 <listitem><para>
486 <emphasis role="bold">iSCSI driver.</emphasis>
487 Transports blocks of iSCSI commands over the IP network.
488 This iSCSI driver is installed on the iSCSI host and is
489 included with the Microsoft iSCSI Initiator.
490 </para></listitem>
491 <listitem><para>
492 <emphasis role="bold">Gigabit Ethernet
493 adapter.</emphasis> Connects to an iSCSI target. Use an
494 Ethernet adapter that can transmit 1000 megabits per
495 second (Mbps). Like standard 10/100 adapters, most
496 gigabit adapters use a preexisting Category 5 or
497 Category 6E cable. Each port on the adapter is
498 identified by a unique IP address.
499 </para></listitem>
500 <listitem><para>
501 <emphasis role="bold">iSCSI target.</emphasis> Is any
502 device that receives iSCSI commands. The device can be
503 an end node such as a storage device, or it can be an
504 intermediate device such as a network bridge between IP
505 and Fibre Channel devices. Each port on the storage
506 array controller or network bridge is identified by one
507 or more IP addresses.
508 </para></listitem>
509 </itemizedlist></listitem>
510 </varlistentry>
511 <varlistentry>
512 <term><option>--intnet</option></term>
513 <listitem><para>
514 Specifies whether to connect to the iSCSI target that uses
515 internal networking. This configuration requires further
516 configuration. See <xref linkend="iscsi-intnet" />.
517 </para></listitem>
518 </varlistentry>
519 </variablelist>
520 </refsect1>
521
522 <refsect1 id="vboxmanage-storageattach-examples">
523 <title>Examples</title>
524 <remark role="help-scope" condition="GLOBAL" />
525 <para>
526 The following command attaches the <filename>o7.vdi</filename>
527 disk image to the specified SATA storage controller on the
528 <filename>ol7</filename> VM.
529 </para>
530<screen>$ storageattach ol7 --storagectl "SATA Controller" --port 0 --device 0 \
531--type hdd --medium /VirtualBox/ol7/ol7.vdi</screen>
532 <para>
533 The following command attaches the
534 <filename>o7-r6-dvd.iso</filename> DVD image to the specified IDE
535 storage controller on the <filename>ol7</filename> VM.
536 </para>
537<screen>$ VBoxManage storageattach ol7 --storagectl "IDE Controller" --port 0 --device 0 \
538--type dvddrive --medium ol7-r6-dvd.iso</screen>
539 </refsect1>
540
541 <refsect1 id="vboxmanage-storageattach-see-also">
542 <title>See Also</title>
543 <para>
544 <xref linkend="vboxmanage-list" />,
545 <xref linkend="vboxmanage-showvminfo" />,
546 <xref linkend="vboxmanage-storagectl" />
547 </para>
548 </refsect1>
549</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