Installation Guide

yo is known to work on Linux and Mac OS. More guinea pigs are necessary for Windows. yo requires at least Python 3.6, and it also requires that you have OpenSSH installed. Yo can make use of the following optionally, if you have them installed:

  • rsync

  • mosh

  • Any RDP or VNC client that can connect via the command line arguments

This document expects that you’ve already created an OCI tenancy, or that you have an account on an existing tenancy. Further, we expect that you’ve already launched an instance once in the Web UI, which should create some default resources for you.

Installation

First, ensure you have at least Python 3.6 installed, along with pip. For Oracle Linux users, yum install python3-pip should do the trick.

pip install yo oci-cli

It’s recommended that you use the above command to install yo. If you run it as a non-root user (recommended), it will install to your home directory. The above will also install the oci-cli package, which will help you configure yo.

Initial Configuration

If you run yo at this point, you should be greeted by a message asking you to configure OCI and/or yo.

OCI Configuration

yo depends on the OCI SDK in order to manage your compute instances. If yo is installed, then the oci command line utility should also be alongside it. The OCI SDK requires some keys to be created and associated with your account, but thankfully, this can be easily achieved with the command:

oci setup bootstrap

Follow the prompts to authenticate with your tenancy. If you don’t know your region, open the OCI Web UI and see what it defaults to.

Please note: if you encounter an error message in the above command which contains the code NotAuthorizedOrNotFound, then there’s an alternative way to setup your OCI credentials:

  1. Run oci setup keys. At the prompt, you probably want to type “N/A” to avoid setting a passphrase for the key. However, if you really feel it is necessary, you can use a passphrase. Yo will detect that it is necessary and prompt you for it.

  2. Open the OCI web console. Navigate to your profile using the icon at the top right (or search your email address in the search bar). On your profile page, select the “API keys” link, and then choose “Add API key”.

  3. Use “choose public key file” to upload the public key generated by step 1, and click submit. The resulting page should contain a fragment of configuration file.

  4. Paste the configuration fragment into ~/.oci/config. Be sure to set key_file to the name of your private key.

yo Configuration

If you run yo without having a configuration file setup, yo will copy the sample configuration file to ~/.oci/yo.ini.

Edit this configuration file. You’ll need to set my_username to a unique username identifying you. Set my_email to your full email address (the one associated with your OCI account – see the OCI console if you’re not sure).

There are a few OCI-related configurations that yo needs you to set, so it knows how to organize your instance and which subnets to use.

  1. region - Choose this to match what you configured before!

  2. instance_compartment_id - Compartments are like containers for resources in OCI. They are useful for larger organizations. You can use the default OCI command line tool oci iam compartment list to explore and select the correct ID. If you have a personal account, you may not use compartments, and instead you can use your tenancy ID.

  3. vcn_id - You can explore the VCNs in your account via oci network vcn list. Use the id field of the desired VCN.

  4. subnet_id - This selects a particular subnet, you can select from the list in oci network subnet list.

  5. Under the [instances.DEFAULT] section, you’ll see an availability_domain configuration. Choose one of the availability domains in your region (try oci iam availability-domain list to get their names).

SSH Key

A major part of managing your OCI instances is being able to access them over SSH. You’ll probably want to take a minute to ensure your SSH key is configured correctly. As a default, Yo assumes your SSH public key is ~/.ssh/id_rsa.pub, but you can change that with the ssh_public_key configuration value in ~/.oci/yo.ini. Please keep the following in mind:

  1. Yo sometimes connects via SSH to execute single commands. If your SSH key is password protected, you may find yourself being prompted for the password more than you’d like. It’s recommended to use an SSH agent to avoid frequent password prompts, or if it is appropriate and secure for your system, to store your SSH key without password protection.

  2. ED25519 keys are supported by some operating systems, but not all. What’s more, the OCI Instance Console Connection service (that is, yo console) does not support ED25519. If you intend to use the serial console, or older OS versions, you should configure a 4096-bit RSA key.

You may find it simplest to just create a SSH key especially for Yo and your OCI instances, then configure that in your ssh_public_key setting:

ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_yo
# enter blank to disable passphrase

Done!

At this point, you should be able to run yo commands, such as yo list. Please continue to the User Guide to understand the basics for how to use Yo.

There are some optional features which yo also supports. If you want to set them up, visit Optional Features to learn more.