Changeset 81007 in vbox

Timestamp:

Sep 25, 2019 2:19:24 PM (5 years ago)

Author:

vboxsync

Message:

bugref:9577. Added 2 chapters into the user manual - \'Importing an instance from Oracle Cloud Infrastructure\' and \'Import from Oracle Cloud Infrastructure\'.

Location:

trunk/doc/manual/en_US

Files:

• user_Introduction.xml (modified) (4 diffs)
• user_VBoxManage.xml (modified) (4 diffs)

trunk/doc/manual/en_US/user_Introduction.xml

@@ -2583 +2583 @@
           <emphasis role="bold">Cloud service formats.</emphasis> Export
           to cloud services such as &oci; is supported. Import is not
-          supported. See <xref linkend="ovf-export-oci"/>.
+          supported. See <xref linkend="cloud-export-oci"/>.
         </para>
       </listitem>
@@ -2853 +2853 @@
               <para>
                 The <emphasis role="bold">&oci;</emphasis> value exports
-                export to &oci;. See <xref linkend="ovf-export-oci"/>.
+                export to &oci;. See <xref linkend="cloud-export-oci"/>.
               </para>
             </listitem>
@@ -2927 +2927 @@
     </sect2>
 
-    <sect2 id="ovf-export-oci">
+    <sect2 id="cloud-export-oci">
 
       <title>Exporting an Appliance to &oci;</title>
@@ -3163 +3163 @@
     </sect2>
 
+    <sect2 id="cloud-import-oci">
+
+      <title>Importing an instance from &oci;</title>
+
+      <para>
+        &product-name; supports the import of cloud instance from an &oci; service.
+      </para>
+
+      <para>
+        Before you can import an instance from &oci;, ensure that you perform the
+        following configuration steps:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Generate an API signing key pair that is used for API
+            requests to &oci;.
+          </para>
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                The key pair is usually installed in the
+                <computeroutput>.oci</computeroutput> folder in your
+                home directory. For example,
+                <computeroutput>~/.oci</computeroutput> on a Linux
+                system.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                Upload the public key of the key pair to the cloud
+                service.
+              </para>
+            </listitem>
+
+          </itemizedlist>
+
+          <para>
+            For step-by-step instructions for creating and uploading an
+            API signing key for &oci;, see:
+          </para>
+
+          <para>
+            <ulink url="https://docs.cloud.oracle.com/iaas/Content/API/Concepts/apisigningkey.htm#How">https://docs.cloud.oracle.com/iaas/Content/API/Concepts/apisigningkey.htm#How</ulink>
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Create a profile for your cloud account.
+          </para>
+
+          <para>
+            The cloud profile contains resource identifiers for your
+            cloud account, such as your user OCID, and the fingerprint
+            for your public key. 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="ovf-cloud-profile-manager"/>.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                Manually by creating an
+                <computeroutput>oci_config</computeroutput> file in your
+                &product-name; global configuration directory. For
+                example, this is
+                <computeroutput>$HOME/.config/VirtualBox/oci_config</computeroutput>
+                on a Linux host.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                Manually by creating a
+                <computeroutput>config</computeroutput> file in your
+                &oci; configuration directory. For example, this is
+                <computeroutput>$HOME/.oci/config</computeroutput> 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
+                <computeroutput>config</computeroutput> 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>
+
+          <para>
+            For more information about the cloud profile settings used
+            by &oci; see:
+          </para>
+
+          <para>
+            <ulink url="https://docs.cloud.oracle.com/iaas/Content/API/Concepts/sdkconfig.htm">https://docs.cloud.oracle.com/iaas/Content/API/Concepts/sdkconfig.htm</ulink>
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        Perform the following steps to import an instance from &oci;:
+      </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">Account</emphasis> drop-down
+            list, select your &oci; account.
+          </para>
+
+          <para>
+            You can set up &oci; accounts by using the Cloud Profile
+            Manager.
+          </para>
+
+          <para>
+            The list after the <emphasis role="bold">Account</emphasis>
+            field shows the profile settings for your cloud account.
+          </para>
+
+          <para>
+            Choose the interesting cloud instance from the list <emphasis role="bold">Machines</emphasis>.
+          </para>
+
+          <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> screen.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Optionally edit settings used for new local virtual machine.
+          </para>
+
+          <para>
+            For example, you can edit the VM name, CPUs, RAM memory, OS type, OS version.
+          </para>
+
+          <para>
+            Click <emphasis role="bold">Import</emphasis> to import the instance from the cloud service.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Monitor the import process by using the &oci; Console.
+          </para>
+        </listitem>
+
+      </orderedlist>
+
+      <para>
+        General OCI import logic:
+      </para>
+      <orderedlist>
+        <listitem>
+          <para>
+            A custom image created from the boot volume of the instance.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            The custom image exported into OCI object and stored in the OCI Object Storage in the bucket pointed by user.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            The OCI object is downloaded to the local host. OCI object is a TAR archive which contains a boot volume of instance
+            in QCOW2 format and JSON file with some meta-data related to the instance.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            The boot volume of instance is extracted from the archive and new VMDK image is created by conversion the boot volume
+            into the VMDK format. The VMDK image is registered in the VirtualBox.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            New VM is created with the VMDK image created on the previous step.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            The downloaded OCI object (TAR archive) is deleted after successful import.
+          </para>
+        </listitem>
+      </orderedlist>
+      <para>
+        By default, the VM isn't launched after import from &oci;.
+      </para>
+
+      <para>
+        You can also use the <command>VBoxManage import</command>
+        command to import an instance from &oci;. See
+        <xref linkend="vboxmanage-import-cloud"/>.
+      </para>
+
+    </sect2>
+
     <sect2 id="ovf-cloud-profile-manager">
 

trunk/doc/manual/en_US/user_VBoxManage.xml

@@ -481 +481 @@
         <para>
           Cloud profiles are used when exporting VMs to a cloud service.
-          See <xref linkend="ovf-export-oci"/>.
+          See <xref linkend="cloud-export-oci"/>.
         </para>
       </listitem>
@@ -2634 +2634 @@
 
     <para>
-      This command imports a virtual appliance in OVF format by copying
-      the virtual disk images and creating virtual machines in
-      &product-name;. See <xref linkend="ovf" /> for an introduction to
-      appliances.
-    </para>
-
-    <para>
-      The <command>import</command> subcommand takes at least the path
-      name of an OVF file as input and expects the disk images, if
-      needed, in the same directory as the OVF file. A lot of additional
-      command-line options are supported to control in detail what is
-      being imported and modify the import parameters, but the details
-      depend on the content of the OVF file.
-    </para>
-
-    <para>
-      It is therefore recommended to first run the
-      <command>import</command> subcommand with the
-      <computeroutput>--dry-run</computeroutput> or
-      <computeroutput>-n</computeroutput> option. This will then print a
-      description of the appliance's contents to the screen how it would
-      be imported into &product-name;, together with the optional
-      command-line options to influence the import behavior.
-    </para>
-
-    <para>
-      Use of the <computeroutput>--options
-      keepallmacs|keepnatmacs|keepdisknames</computeroutput> option
-      enables additional fine tuning of the clone operation. The first
-      two options enable specification of how the MAC addresses of every
-      virtual network card should be handled. They can either be
-      reinitialized, which is the default setting, left unchanged
-      (<computeroutput>keepallmacs</computeroutput>) or left unchanged
-      when the network type is NAT
-      (<computeroutput>keepnatmacs</computeroutput>). If you add
-      <computeroutput>keepdisknames</computeroutput> all new disk images
-      are assigned the same names as the originals, otherwise they are
-      renamed.
-    </para>
-
-    <para>
-      As an example, the following is a screen output for a sample
-      appliance containing a Windows XP guest:
-    </para>
-
-<screen>VBoxManage import WindowsXp.ovf --dry-run
-Interpreting WindowsXp.ovf...
-OK.
-Virtual system 0:
- 0: Suggested OS type: "WindowsXP"
-    (change with "--vsys 0 --ostype &lt;type&gt;"; use "list ostypes" to list all)
- 1: Suggested VM name "Windows XP Professional_1"
-    (change with "--vsys 0 --vmname &lt;name&gt;")
- 2: Suggested VM group "/"
-    (change with "--vsys 0 --group &lt;group&gt;")
- 3: Suggested VM settings file name "/home/klaus/VirtualBox VMs/dummy2 2/dummy2 2.vbox"
-    (change with "--vsys 0 --settingsfile &lt;filename&gt;")
- 4: Suggested VM base folder "/home/klaus/VirtualBox VMs"
-    (change with "--vsys 0 --basefolder &lt;path&gt;")
- 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 &lt;n&gt;")
- 7: Guest memory: 956 MB (change with "--vsys 0 --memory &lt;MB&gt;")
- 8: Sound card (appliance expects "ensoniq1371", can change on import)
-    (disable with "--vsys 0 --unit 5 --ignore")
- 9: USB controller
-    (disable with "--vsys 0 --unit 6 --ignore")
-10: Network adapter: orig bridged, config 2, extra type=bridged
-11: Floppy
-    (disable with "--vsys 0 --unit 8 --ignore")
-12: SCSI controller, type BusLogic
-    (change with "--vsys 0 --unit 9 --scsitype {BusLogic|LsiLogic}";
-    disable with "--vsys 0 --unit 9 --ignore")
-13: IDE controller, type PIIX4
-    (disable with "--vsys 0 --unit 10 --ignore")
-14: Hard disk image: source image=WindowsXp.vmdk,
-      target path=/home/user/disks/WindowsXp.vmdk, controller=9;channel=0
-    (change controller with "--vsys 0 --unit 11 --controller &lt;id&gt;";
-    disable with "--vsys 0 --unit 11 --ignore")</screen>
-
-    <para>
-      The individual configuration items are numbered, and depending on
-      their type support different command-line options. The import
-      subcommand can be directed to ignore many such items with a
-      <computeroutput>--vsys X --unit Y --ignore</computeroutput>
-      option, where X is the number of the virtual system and Y the item
-      number, as printed on the screen. X is zero, unless there are
-      several virtual system descriptions in the appliance.
-    </para>
-
-    <para>
-      In the above example, Item #1 specifies the name of the target
-      machine in &product-name;. Items #9 and #10 specify hard disk
-      controllers, respectively. Item #11 describes a hard disk image.
-      In this case, the additional
-      <computeroutput>--controller</computeroutput> option indicates
-      which item the disk image should be connected to, with the default
-      coming from the OVF file.
-    </para>
-
-    <para>
-      You can combine several items for the same virtual system behind
-      the same <computeroutput>--vsys</computeroutput> option. For
-      example, to import a machine as described in the OVF, but without
-      the sound card and without the USB controller, and with the disk
-      image connected to the IDE controller instead of the SCSI
-      controller, use the following command:
-    </para>
-
-<screen>VBoxManage import WindowsXp.ovf
-      --vsys 0 --unit 5 --ignore --unit 6 --ignore --unit 11 --controller 10</screen>
+      This command import one or more virtual machines to
+      &product-name;. You can import from either of the following:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          A virtual appliance in OVF format.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          A cloud service, such as &oci;. Only a single cloud instance can be imported.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      See <xref linkend="ovf" /> for more details on importing VMs from
+      &product-name;.
+    </para>
+
+    <sect2 id="vboxmanage-import-ovf">
+
+      <title>Import from OVF</title>
+
+      <para>
+        The <command>import</command> subcommand takes at least the path
+        name of an OVF file as input and expects the disk images, if
+        needed, in the same directory as the OVF file. A lot of additional
+        command-line options are supported to control in detail what is
+        being imported and modify the import parameters, but the details
+        depend on the content of the OVF file.
+      </para>
+
+      <para>
+        It is therefore recommended to first run the
+        <command>import</command> subcommand with the
+        <computeroutput>--dry-run</computeroutput> or
+        <computeroutput>-n</computeroutput> option. This will then print a
+        description of the appliance's contents to the screen how it would
+        be imported into &product-name;, together with the optional
+        command-line options to influence the import behavior.
+      </para>
+
+      <para>
+        Use of the <computeroutput>--options
+        keepallmacs|keepnatmacs|keepdisknames</computeroutput> option
+        enables additional fine tuning of the clone operation. The first
+        two options enable specification of how the MAC addresses of every
+        virtual network card should be handled. They can either be
+        reinitialized, which is the default setting, left unchanged
+        (<computeroutput>keepallmacs</computeroutput>) or left unchanged
+        when the network type is NAT
+        (<computeroutput>keepnatmacs</computeroutput>). If you add
+        <computeroutput>keepdisknames</computeroutput> all new disk images
+        are assigned the same names as the originals, otherwise they are
+        renamed.
+      </para>
+
+      <para>
+        As an example, the following is a screen output for a sample
+        appliance containing a Windows XP guest:
+      </para>
+
+      <screen>VBoxManage import WindowsXp.ovf --dry-run
+      Interpreting WindowsXp.ovf...
+      OK.
+      Virtual system 0:
+       0: Suggested OS type: "WindowsXP"
+          (change with "--vsys 0 --ostype &lt;type&gt;"; use "list ostypes" to list all)
+       1: Suggested VM name "Windows XP Professional_1"
+          (change with "--vsys 0 --vmname &lt;name&gt;")
+       2: Suggested VM group "/"
+          (change with "--vsys 0 --group &lt;group&gt;")
+       3: Suggested VM settings file name "/home/klaus/VirtualBox VMs/dummy2 2/dummy2 2.vbox"
+          (change with "--vsys 0 --settingsfile &lt;filename&gt;")
+       4: Suggested VM base folder "/home/klaus/VirtualBox VMs"
+          (change with "--vsys 0 --basefolder &lt;path&gt;")
+       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 &lt;n&gt;")
+       7: Guest memory: 956 MB (change with "--vsys 0 --memory &lt;MB&gt;")
+       8: Sound card (appliance expects "ensoniq1371", can change on import)
+          (disable with "--vsys 0 --unit 5 --ignore")
+       9: USB controller
+          (disable with "--vsys 0 --unit 6 --ignore")
+      10: Network adapter: orig bridged, config 2, extra type=bridged
+      11: Floppy
+          (disable with "--vsys 0 --unit 8 --ignore")
+      12: SCSI controller, type BusLogic
+          (change with "--vsys 0 --unit 9 --scsitype {BusLogic|LsiLogic}";
+          disable with "--vsys 0 --unit 9 --ignore")
+      13: IDE controller, type PIIX4
+          (disable with "--vsys 0 --unit 10 --ignore")
+      14: Hard disk image: source image=WindowsXp.vmdk,
+            target path=/home/user/disks/WindowsXp.vmdk, controller=9;channel=0
+          (change controller with "--vsys 0 --unit 11 --controller &lt;id&gt;";
+          disable with "--vsys 0 --unit 11 --ignore")</screen>
+
+      <para>
+        The individual configuration items are numbered, and depending on
+        their type support different command-line options. The import
+        subcommand can be directed to ignore many such items with a
+        <computeroutput>--vsys X --unit Y --ignore</computeroutput>
+        option, where X is the number of the virtual system and Y the item
+        number, as printed on the screen. X is zero, unless there are
+        several virtual system descriptions in the appliance.
+      </para>
+
+      <para>
+        In the above example, Item #1 specifies the name of the target
+        machine in &product-name;. Items #9 and #10 specify hard disk
+        controllers, respectively. Item #11 describes a hard disk image.
+        In this case, the additional
+        <computeroutput>--controller</computeroutput> option indicates
+        which item the disk image should be connected to, with the default
+        coming from the OVF file.
+      </para>
+
+      <para>
+        You can combine several items for the same virtual system behind
+        the same <computeroutput>--vsys</computeroutput> option. For
+        example, to import a machine as described in the OVF, but without
+        the sound card and without the USB controller, and with the disk
+        image connected to the IDE controller instead of the SCSI
+        controller, use the following command:
+      </para>
+
+      <screen>VBoxManage import WindowsXp.ovf
+            --vsys 0 --unit 5 --ignore --unit 6 --ignore --unit 11 --controller 10</screen>
+    </sect2>
+
+    <sect2 id="vboxmanage-import-cloud">
+      <title>Import from &oci;</title>
+      <para>
+        As the result of operation a file with the suffix “.oci” will be downloaded 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 downloaded file is deleted after successful import. If import fails the VBoxSVC log file
+        may hint a name and place where the downloaded file was stored (in case of failure the file may not be deleted).
+        During import the bootable image is extracted from the archive and converted into VMDK format. The JSON file is also extracted
+        and stored in the VM folder.
+      </para>
+      <para>
+        The command syntax begins from the "VBoxManage import OCI:// --cloud".
+      </para>
+      <para>
+        List the machines and their ids from Oracle Cloud Infrastructure using the command "VBoxManage cloud --provider=OCI
+        --profile="your profile name" list instances".
+      </para>
+      <para>
+        To import a VM from a cloud service such as Oracle Cloud Infrastructure, use the <option>--cloud</option> option to specify the
+        import from the Cloud. Some of the following options are settings for the VM. Somewhere you must enter an Oracle Cloud Identifier (OCID)
+        for a resource. Use the Oracle Cloud Infrastructure Console to view OCIDs.
+      </para>
+      <para>
+        Next parameters must be followed:
+        <itemizedlist>
+          <listitem>
+            <para>
+              <option>--vmname</option>: Specifies new name for imported VM. This name is used as the VM name in VirtualBox.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <option>--cloudinstanceid</option>: Id of existing instance in the Cloud.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <option>--cloudprofile</option>: Specifies the cloud profile that is used to connect to the cloud service provider.
+              The cloud profile contains your Oracle Cloud Infrastructure 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 Oracle Cloud Infrastructure.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <option>--cloudbucket</option>: Specifies the bucket name in which to store the object created from an instance bootable volume.
+              In Oracle Cloud Infrastructure, a bucket is a logical container for storing objects.
+            </para>
+          </listitem>
+        </itemizedlist>
+      </para>
+      <para>
+        Some other import options have the same meaning as for OVF import:
+        <itemizedlist>
+          <listitem>
+            <para>
+              <option>--ostype</option>: OS type supported by VirtualBox. Use "VBoxManage list ostypes" to see the whole list of supported OSes.
+              If the type wasn't set the "Unknown" type will be used.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <option>--basefolder</option>: folder where new VM will be placed.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <option>--description</option>: VM description string.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <option>--memory</option>: RAM memory assigned for VM in MB.
+              If memory wasn't set the possible memory size will be deduced from the default memory size for this OS type or will be taken from the cloud instance.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <option>--cpus</option>: Number of virtual CPUs assigned for VM.
+              If cpus wasn't set the possible number of CPUs will be deduced from the default settings for this OS type or will be taken from the cloud instance.
+            </para>
+          </listitem>
+        </itemizedlist>
+      </para>
+      <para>
+        The import options <option>--disk</option>, <option>--controller</option>, <option>--scsitype</option>, <option>--unit</option>,
+        <option>--settingsfile</option> are invalid for cloud import.
+      </para>
+      <para>
+        The following example shows a typical command line for import an instance from Oracle Cloud Infrastructure:
+      </para>
+        <screen>
+        # VBoxManage import OCI:// --cloud --vmname import_from_oci --memory 4000
+        --cpus 3 --ostype FreeBSD_64 --cloudprofile "standard user" --cloudinstanceid
+        ocid1.instance.oc1.iad.abuwc... --cloudbucket myBucket
+        </screen>
+
+    </sect2>
 
   </sect1>
@@ -2904 +3026 @@
             provider. The cloud profile contains your &oci; account
             details, such as your user OCID and the fingerprint for your
-            public key. See <xref linkend="ovf-export-oci"/>.
+            public key. See <xref linkend="cloud-export-oci"/>.
           </para>
 
@@ -3007 +3129 @@
       </remark>
 
-<screen># VBoxManage export myVM --output OCI:// --cloud 0 --vmname myVM_Cloud \
---cloudprofile "standard user" --cloudbucket myBucket \
---cloudshape VM.Standard2.1 --clouddomain aaaa:US-ASHBURN-AD-1 --clouddisksize 50  \
---cloudocivcn ocid1.vcn.oc1.iad.aaaa... --cloudocisubnet ocid1.subnet.oc1.iad.aaaa... \
+<screen># VBoxManage export myVM --output OCI:// --cloud 0 --vmname myVM_Cloud
+--cloudprofile "standard user" --cloudbucket myBucket
+--cloudshape VM.Standard2.1 --clouddomain aaaa: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>