Oracle Cloud Infrastructure Documentation

Getting Started with the Command Line Interface

This topic provides a walk-through of the commands required to launch a Linux instance and a Windows instance. This tutorial includes working with a compartment, creating a virtual cloud network, and launching instances.

About the Command Line Interface (CLI)

The CLI is a tool that lets you work with most of the available services in Oracle Cloud Infrastructure. The CLI provides the same core functionality as the Console, plus additional commands. The CLI's functionality and command help are based on the service's API.

Getting Help with Commands

You can get inline help using the --help, -h, or -? keywords. For example:

oci --help
oci bv volume -h
oci os bucket create -?

You can also view all the CLI help in your browser.

About the CLI Examples

The examples in this document are grouped as a command and a response, where:

  • You are told what the command does, and given the command to use
  • The result of the command is returned in a drop-down text box

The next example shows a command and response group.

To get the namespace for your tenancy, run the following command.

oci os ns get

Response

Most of the command and response groups in this guide aren't as simple as the preceding example. However, as you work through the tasks, they are easier to read and work with.

Before You Begin

Before you start using the command line interface, verify that you meet all the requirements described in Command Line Interface (CLI).

As a best practice, complete the tasks in this tutorial in a test environment. This approach ensures that your configurations do not affect other environments in the tenancy. At the end of the tutorial, you can safely delete the test resources.

Working in a Compartment

In this tutorial, you use one compartment for all your resources. When you are ready to create a production environment, you will most likely separate these resources in different compartments.

You can either use an existing compartment (recommended), or create a new compartment.

Choose a Compartment

Help: oci iam compartment list -h

To list the compartments in your tenancy, run the following command.

oci iam compartment list -c <tenancy_id>
Command Example and Response

Create a Compartment

Help: oci iam compartment create -h

Before you create a compartment, review Working with Compartments to understand compartment design, resource management, and compartment constraints.

To create a compartment, run the following command.

oci iam compartment create --name <compartment_name> -c <root_compartment_id> --description "<friendly_description>"
Warning

Avoid entering confidential information when providing resource names or descriptions for any of the CLI commands.

Command Example and Response
Tip

Keep track of the information that's returned when you run commands. In several cases, you need this information as you work through this document. For example, the preceding command returns the OCID for the tenancy, which is also the root compartment.

"compartment-id": "ocid1.tenancy.oc1..aaaaaaaawuu4tdkysd2ups5fsclgm5ksfjwmx6mwem5sbjyw5ob5ojq2vkxa"

Creating a Virtual Cloud Network

Before you can launch any instances, you have to create a virtual cloud network (VCN) and related resources. The following tasks are used to prepare the network environment:

  1. Create the Virtual Cloud Network

    Help: oci network vcn create -h

    Create the VCN, specifying a DNS name and a CIDR block range.

    To create the VCN, run the following command.

    oci network vcn create --compartment-id <compartment_id> --display-name "<friendly_name>" --dns-label <dns_name> --cidr-block "<0.0.0.0/0>"
    Command Example and Response

    You can get information about any of your configurations by sending queries to your tenancy.

    For example, to get network information, run the following command.

    oci network vcn list -c <compartment_id>
    Command Example and Response
  2. Configure a Security List Ingress Rule

    Help: oci network security-list create -h

    When you create a VCN, a default security list is created for you. However, the Windows instance also requires inbound traffic enabled for port 3389. The preferred approach is creating a second list that addresses the Windows port requirement. You use the --security-list-ids option to associate both security lists with the subnet when you create it.

    Note

    Passing JSON Strings in the CLI

    The next command passes complex input as a JSON text string. For help with formatting JSON input, especially when working in a Windows environment, see Passing Complex Input.

    To create a new security list and configure the ingress rule for port 3389, run the following command.

    oci network security-list create -c <compartment_id> --egress-security-rules "[{"destination": "<0.0.0.0/0>", "protocol": "<6>", "isStateless": <true>, "tcpOptions": {"destinationPortRange": <null>, "sourcePortRange": <null>}}]" --ingress-security-rules "[{"source": "<0.0.0.0/0>", "protocol": "<6>", "isStateless": <false>, "tcpOptions": {"destinationPortRange": {"max": <3389>, "min": <3389>}, "sourcePortRange": <null>}}]" --vcn-id <vcn_id> --display-name <rule_name>
    Command Example and Response
  3. Create a Subnet

    Help: oci iam availability-domain list -h, oci network subnet create -h

    In this next step, you have to provide the OCIDs for the default security list and the new security list. If you didn't record these OCIDs, use the oci network security-list list command to get a list of the security lists in the virtual cloud network.

    Before you create a subnet, you have to find out which availability domains are available to create the subnet in.

    To get the availability domain list for your compartment, run the following command.

    oci iam availability-domain list -c <compartment_id>
    Command Example and Response

    To create a subnet in AD-1, run the following command.

    oci network subnet create --vcn-id <vcn_id> -c <compartment_id>  --availability-domain "<availability_domain_name>" --display-name <display_name> --dns-label "<dns_label>" --cidr-block "<10.0.0.0/16>" --security-list-ids "["<default_security_list_id>","<new_security_list_id>"]"
    Command Example and Response
  4. Create an Internet Gateway

    Help: oci network internet-gateway create -h

    To create an Internet Gateway, run the following command.

    oci network internet-gateway create -c <compartment_id> --is-enabled <true> --vcn-id <vcn_id> --display-name <gateway_display_name>
    Command Example and Response
  5. Add a Rule to the Route Table

    Help: oci network route-table list -h, oci network route-table update -h

    When you create a VCN, a route table is created automatically. Before you add a rule to the route table, you need the OCID for the table.

    To get the route table OCID, run the following command.

    oci network route-table list -c <compartment_id> --vcn-id <vcn_id>
    Command Example and Response

    The information in the previous response shows that there is a route table without any rules: "route rules":[]. Because the table exists, you create a rule by updating the table. When you run the next command, you get a warning about updates to route rules. Any update to the route rules replaces all the existing rules. If you want to continue and process the update, Enter "y".

    To update the route rules, run the following command.

    oci network route-table update --rt-id <route_table_id> --route-rules "[{"cidrBlock":"<0.0.0.0/0>","networkEntityId":"<internet_gateway_id>"}]
    WARNING: Updates to route-rules will replace any existing values. Are you sure you want to continue? [y/N]: y
    Command Example and Response

Preparing to Launch an Instance

When you launch an instance you have to provide the following information, some of which you've already obtained:

  • compartment-id
  • availability-domain
  • subnet-id
  • image-id
  • shape
  1. Get Information About the Available Images

    Help: oci compute image list -h

    The image-id identifies the operating system that you want to install. For more information, see Oracle-Provided Images.

    To get a list of images, run the following command.

    oci compute image list -c <compartment_id>
    Command Example and Response
  2. Get Information About the Available Shapes

    Help: oci compute shape list -h

    The shape identifies the configuration of the virtual machine or bare metal host that you want to use. Overview of the Compute Service contains up-to-date information about the available shapes.

    For the purposes of this walk-through, use this virtual machine shape for testing: --shape "VM.Standard1.1". This shape is configured with 1 CPU and 7 GB of memory.

    Note

    Shape and Block Volume Sizing

    Sizing for compute instance shapes and block volumes are not part of this walk-through. The examples use the minimum sizes that are available.

    To get a list of all the available bare metal and virtual machine shapes, run the following command.

    oci compute shape list -c <compartment_id> --availability-domain "<availability_domain_name>"
    Command Example and Response

Launching a Linux Instance

Now you're ready to launch a Linux instance based on the configurations you prepared.

  1. Use a Public/Private Key Pair to Connect to the Instance

    When you launch an instance using the CLI, you need an existing key pair to access the instance. (This key pair is not the same as an API signing key.)

  2. Launch the Instance

    Help: oci compute instance launch -h

    Warning

    In this example, the --ssh-authorized-keys-file parameter references a file that contains the public key required to access the compute instance. If you don't provide this key when you launch the instance you can't connect to the instance after it's launched.

    To launch the Linux instance, run the following command.

    oci compute instance launch --availability-domain "<availability_domain_name>" -c <compartment_id> --shape "<shape_name>"   --display-name "<instance_display_name>"   --image-id <image_id> --ssh-authorized-keys-file "<path_to_authorized_keys_file>" --subnet-id  <subnet_id>
    Command Example and Response
  3. Get VNIC Information for the Instance

    Help: oci compute instance list-vnics -h

    You need the public IP address of the instance in order to connect to the instance. The VNIC for the instance has this information.

    To get a list of VNICs for the instance, run the following command.

    oci compute instance list-vnics --instance-id <instance_id>
    Command Example and Response
  4. Create a Block Volume for the Instance

    Help: oci bv volume create -h

    Create a block volume, using the minimum available size.

    Warning

    Block volume sizes are expressed as increments of 1024 MB. The next command example uses the minimum size, --size-in-mbs 51200, or 50 GB.

    To create a block volume, run the following command.

    oci bv volume create --availability-domain "<availability_domain_name>" -c <compartment_id> --size-in-mbs <51200> --display-name <volume_display_name>
    Command Example and Response
  5. After the lifecycle state changes from "PROVISIONING" to "AVAILABLE" you can attach the volume to the Linux instance.

    Tip

    Finding out the Lifecycle State

    You can find out the lifecycle state for the block volume using the oci bv volume get command for the volume you created. You can also query other resources such as compute instances and VNICs, to find out their lifecycle state.

  6. Attach the Block Volume to the Instance

    Help: oci compute volume-attachment attach -h

    To attach the block volume to the Linux instance, run the following command.

    oci compute volume-attachment attach --instance-id <instance_id> --type <iscsi> --volume-id <volume_id>
    Command Example and Response

Launching a Windows Instance

Launching a Windows instance follows the same pattern and requires the same information as launching a Linux instance. The only significant differences are the operating system and shape, as shown in the following commands.

  1. Launch the Instance

    Help: oci compute instance launch -h

    To launch the Windows instance, run the following command.

    oci compute instance launch --availability-domain "<availability_domain_name>" -c <compartment_id> --shape "<shape_name>"   --display-name "<instance_display_name>" --image-id <image_id> --subnet-id <subnet_id>
    Command Example and Response
  2. Get VNIC Information for the Instance

    To get the VNIC information, run the following command.

    oci compute instance list-vnics --instance-id <instance_id>
  3. Create a Block Volume for the Instance

    To create a block volume, run the following command.

    oci bv volume create --availability-domain "<availability_domain_name>" -c <compartment_id> --size-in-mbs <51200> --display-name <display_name>
  4. Attach the Block Volume to the Instance

    To attach the Block Volume to the Windows instance, run the following command.

    oci compute volume-attachment attach --instance-id <instance_id> --type <iscsi> --volume-id <volume_id>

Connecting to Your Instances

Although the Public IP address is required for connecting to Linux and Windows instances, that is the only thing the two have in common. Some of these differences include: authentication, port configuration, and desktop client programs.

  1. Connect to Your Linux Instance

    Connecting to Your Instance describes how to connect to a Linux instance from a Unix-style or Windows-style system.

  2. Connect to Your Windows Instance

    Help: oci compute instance list-vnics -h and oci compute instance get-windows-initial-creds -h

    To connect to the instance using Remote Desktop Client (RDC), you need:

    • The public IP address for the instance
    • The initial Windows credentials

    To get the public IP address of the Windows instance, run the following command.

    oci compute instance list-vnics --instance-id <instance_id>
    Command Example and Response

    To get the initial Windows credentials, run the following command.

    oci compute instance get-windows-initial-creds --instance-id  <instance_id>
    Command Example and Response

    Connecting to Your Windows Instance describes how to connect to your instance using RDC.

Cleaning Up the Test Environment

When you've finished setting up the test environments described in this tutorial, clean up the test environment by removing resources you aren't using.

Detach and Delete the Block Volumes

Help: oci compute volume-attachment list -h , oci compute volume-attachment detach -h and oci bv volume delete -h

Removing a block volume from an instance is a 3-step process. Use the following steps to detach and delete the block volume for the Linux instance.

  1. Get the volume-attachment-id

    The volume attachment ID is created when you create a block volume.

    To get the volume attachment ID, run the following command.

    oci compute volume-attachment list -c <compartment_id>
    Command Example and Response
  2. Detach the volume-attachment-id

    To detach the volume attachment-id, run the following command.

    oci compute volume-attachment detach --volume-attachment-id <volume_attachment_id>
    Command Example and Response
  3. Delete the Block Volume

    To delete the block volume, run the following command.

    oci bv volume delete --volume-id <volume_id> --force
    Command Example and Response

To delete the block volume attached to the Windows instance, use the preceding steps (1-3) as a guide.

Terminate the Instances

Help: oci compute instance terminate -h

To delete the Linux instance, run the following command.

oci compute instance terminate --instance-id <instance_id>
Command Example and Response

To delete the Windows instance, run the following command.

oci compute instance terminate --instance-id <instance_id>
Command Example and Response

Delete the Virtual Cloud Network

Help: oci network subnet delete -h, oci network vcn delete -h

It takes the following 2 steps to delete the VCN.

  1. Delete the subnet

    To delete the subnet, run the following command.

     oci network subnet delete --subnet-id <subnet_id> --force
    Command Example and Response
  2. Delete the virtual cloud network

    To delete the VCN, run the following command.

    oci network vcn delete --vcn-id  <vcn_id> --force
    Command Example and Response