# Getting Started ## Getting Started If you choose to use node-triton or node-smartdc, be aware that they both require Node.js. You can get Node.js from [nodejs.org](http://nodejs.org/) as source code, and as precompiled packages for Windows, Macintosh, Linux and Illumos distributions. Alternatively, when using a \*nix, you can usually install Node.js using a package manager as well (e.g. pkgsrc, brew, apt-get, yum). The version of Node.js should be at least v0.10, so npm (Node.js's package manager) should come with it as well. Once you've installed Node.js, to install node-triton invoke: ``` npm install -g triton ``` or, to install node-smartdc: ``` npm install -g smartdc ``` You will probably want to install [json](https://www.npmjs.org/package/json) as well. It is a tool that makes it easier to work with JSON-formatted output. You can install it like this: ``` npm install -g json ``` In all cases above, the `-g` switch installs the tools globally, usually in `/usr/local/bin`, so that you can use them easily from the command line. Omit this switch if you'd rather the tools be installed in your home hierarchy, but you'll need to set your PATH appropriately. ### Generate an SSH key Both CLIs require an SSH key to communicate with CloudAPI, as well as logging-in to many instances. If you haven't already generated an SSH key (required to use both SSH and HTTP Signing), run the following command: ``` ssh-keygen -b 2048 -t rsa -m PEM ``` This will prompt you with a place to save the key. You should probably just accept the defaults, as many programs (SSH and CloudAPI CLIs) will first look for a file called \~/.ssh/id\_rsa. Before running the above command, ensure that \~/.ssh/id\_rsa does not already exist; overwriting it may have unintended consequences. ### Set Up your CLI You need to set the following environment variables information in order to interact with CloudAPI using either node-triton or node-smartdc: * `SDC_URL`: The URL of the CloudAPI endpoint. * `SDC_KEY_ID`: Fingerprint for the key you uploaded to Triton. * `SDC_ACCOUNT`: Your username; the login you use for Triton. * `SDC_USER`: If authenticating as a subuser, the username of the subuser. See [Role Based Access Control](https://apidocs.joyent.com/cloudapi/#rbac-users-roles-policies). * `SDC_TESTING`: If using a self-signed SSL certificate, set this to 1. An example for `SDC_URL` is `https://us-west-1.api.joyent.com`. Each datacenter in a cloud has its own CloudAPI endpoint; a different cloud that uses Triton would have a different URL. In this document, we'll use `api.example.com` as the `SDC_URL` endpoint; please replace it with the URL of your datacenter(s). Note that CloudAPI always uses SSL/TLS, which means that the endpoint URL must begin with `https`. You can quickly get your key fingerprint for `SDC_KEY_ID` by running: ``` ssh-keygen -l -f ~/.ssh/id_rsa.pub | awk '{print $2}' | tr -d '\n' ``` where you replace `~/.ssh/id_rsa.pub` with the path to the public key you want to use for signing requests. ### Working with the CLI For a complete list of CloudAPI CLI commands available, please see [Appendix C: CloudAPI CLI Commands](https://apidocs.joyent.com/cloudapi/#appendix-c-cloudapi-cli-commands). To get help on a command, use the `--help` flag. For example: ``` triton datacenters --help Show datacenters in this cloud. A "cloud" is a set of related datacenters that share account information. Usage: triton datacenters Options: -h, --help Show this help. Output options: -H Omit table header row. -o field1,... Specify fields (columns) to output. -s field1,... Sort on the given fields. Default is "name". -j, --json JSON output. ``` or ``` sdc-listdatacenters --help sdc-listdatacenters [--account string] [--api-version string] [--debug boolean] [--help boolean] [--keyId string] [--url url] [--version boolean] [--verbose boolean] [--user string] [--role string] ``` You can set environment variables for the following flags so that you don't have to type them for each request (e.g. in your .bash\_profile). All the examples in this document assume that these variables have been set: | **CLI Flags** | **Description** | **Environment Variable** | | ---------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------ | |

--account
-a

| Login name (account) | SDC\_ACCOUNT | | --user | Subuser name when using [Role Based Access Control](https://apidocs.joyent.com/cloudapi/#rbac-users-roles-policies) | SDC\_USER | |

--keyId
-k

| Fingerprint of key to use for signing | SDC\_KEY\_ID | |

--url
-u

| URL of the CloudAPI endpoint | SDC\_URL | ### Provision a new instance To provision a new instance, you first need to get the `id`s for the image and package you want to use as the base for your instance. An image is a snapshot of a filesystem and its software (for some types of container), or a disk image (for hardware virtual machines). You can get the list of available images using the `triton image list` or `sdc-listimages` commands; see the [ListImages](https://apidocs.joyent.com/cloudapi/#ListImages) section below for a detailed explanation of these commands. A package is a set of dimensions for the new instance, such as RAM and disk size. You can get the list of available packages using the `triton package list` or `sdc-listpackages` commands; see the [ListPackages](https://apidocs.joyent.com/cloudapi/#ListPackages) section below for a detailed explanation of these commands. Once you have the package and image ids, to provision a new instance: ``` triton instance create $image $package ``` or ``` sdc-createmachine --image=$image --package=$package ``` For example: ``` triton instance create 2b683a82-a066-11e3-97ab-2faa44701c5a 64e23114-d502-c171-967f-b0e0cfb2009a Creating instance 61dc8be (9205af5b-f2c0-ef07-e1f3-94bf1ff8fb93, base@13.4.0, test_128) ``` You can use the `--name` flag to name your instance; if you do not specify a name, Triton will generate one for you. `--image` is the `id` of the image you'd like to use as the new instance's base. `--package` is the `id` of the package to use to set instance dimensions. For the `triton` command, you can also pass the name of the image or the package instead of their id. Retrieve the status of your new instance by: ``` triton instance get $instance_id ``` or ``` sdc-getmachine $instance_id ``` For example: ``` triton instance get 9205af5b-f2c0-ef07-e1f3-94bf1ff8fb93 { "id": "9205af5b-f2c0-ef07-e1f3-94bf1ff8fb93", "name": "61dc8be", "type": "smartmachine", "brand": "joyent", "state": "running", "image": "2b683a82-a066-11e3-97ab-2faa44701c5a", "ips": [ "10.88.88.56", "192.168.128.5" ], "memory": 128, "disk": 12288, "metadata": { "root_authorized_keys": "<...>" }, "tags": {}, "created": "2015-12-06T04:31:17.053Z", "updated": "2015-12-06T04:31:26.000Z", "networks": [ "67f1232c-5b40-4693-8b55-560245984233", "05dcc9e2-8ae6-48d9-8222-25f64465693f" ], "primaryIp": "10.88.88.56", "firewall_enabled": false, "compute_node": "564d0b8e-6099-7648-351e-877faf6c56f6", "package": "test_128" } ``` When you provision a new instance, the instance will take time to be initialized and booted; the `state` attribute will reflect this. Once the `state` attribute "running", you can login to your new instance (assuming it's a Unix-based instance), with the following: ``` ssh-add ~/.ssh/ $ ssh -A root@ ``` These two commands set up your SSH agent (which has some magical properties, so you need to handle your SSH keys less often), and logs you in as the `admin` user on an instance. Note that the `admin` user has password-less sudo capabilities, so you may want to set up some less privileged users. The SSH keys on your account will allow you to login as `root` or `admin` on your new instance. An alternative of using SSH directly is: ``` triton ssh ``` Now that we've done some basics with an instance, let's introduce a few concepts: #### Images By default, SmartOS images should be available to your for use. Your Triton cloud may have other images available as well, such as Linux or Windows images. The list of available images can be obtained with: ``` triton image list ``` or ``` sdc-listimages ``` For example: ``` triton image list SHORTID NAME VERSION FLAGS OS TYPE PUBDATE e1faace4 minimal-64-lts 15.4.1 P smartos zone-dataset 2016-03-03 ``` #### Packages You can list packages available in your cloud with: ``` triton package list ``` or ``` sdc-listpackages ``` For example: ``` ./triton package list SHORTID NAME DEFAULT MEMORY SWAP DISK VCPUS 64e23114 test_128 false 128M 256M 12G 1 ``` Packages are the Triton name for the dimensions of an instance (how much CPU will be available, how much RAM, disk and swap, and so forth). Packages are provided so that you do not need to select individual settings, such as RAM or disk size. ### Managing SSH keys For instances which don't have a `brand` of `kvm` or `bhyve` (see `triton instance list -o id,brand` or `sdc-listmachines`), you can manage the SSH keys that allow logging into the instance via CloudAPI. For example, to rotate keys: ``` triton key add --name=my-other-rsa-key ~/.ssh/my_other_rsa_key.pub ``` or ``` sdc-createkey --name=my-other-rsa-key ~/.ssh/my_other_rsa_key.pub ``` The `--name` option sets the name of the key. If you don't provide one, CloudAPI sets it to the name of the file; in this case `my_other_rsa_key.pub`. To use the new key, you will need to update the environment variables: ``` export SDC_KEY_ID=`ssh-keygen -l -f ~/.ssh/my_other_rsa_key.pub | awk '{print $2}' | tr -d '\n'` ``` At this point you could delete your other key from the system; see [Cleaning Up](https://apidocs.joyent.com/cloudapi/#cleaning-up) for a quick example. You cannot manage the SSH keys of instances with a `brand` of `kvm` or `bhyve`. Hardware virtual machines are static, and whatever keys were in your account at instance creation time are used, provided the OS inside KVM is a \*nix. ### Cleaning up After going through this `Getting Started` section, you should now have at least one SSH key and one instance. The rest of the commands assume you have [json](https://www.npmjs.org/package/json) installed. #### Deleting Machines To clean up an instance, you can use either: ``` triton instance delete $instance_id ``` or ``` sdc-deletemachine $instance_id ``` For example: ``` triton instance delete 9205af5b Delete (async) instance 9205af5b (9205af5b-f2c0-ef07-e1f3-94bf1ff8fb93) ``` #### Deleting keys Finally, you probably have one or two SSH keys uploaded to Triton after going through the guide, so to delete the one we setup: ``` triton key delete id_rsa ``` or ``` sdc-deletekey id_rsa ```