Tutorial

How To Use Tugboat to Manage DigitalOcean Droplets from a Terminal

Published on September 12, 2013
How To Use Tugboat to Manage DigitalOcean Droplets from a Terminal

Introduction


If you are reading this article, then you are probably familiar with how to manage your DigitalOcean droplets from within the Control Panel.

Tugboat is an exciting open source application written by Jack Pearkes and other contributors that can be used to manage your droplets from a command line interface.

In this guide, we will install and configure Tugboat using an Ubuntu 14.04 VPS. This will act as the “control” droplet for our other DigitalOcean droplets.

Table Of Contents


<a id=“install”></a>How To Install Tugboat


Log into your new droplet through SSH or by clicking the Console Access button on the droplet page.

Tugboat is a Ruby application, which means that we can install it easily using the RubyGems package manager.

First, we need to install Ruby from Ubuntu’s default repositories:

sudo apt-get update
sudo apt-get install ruby ruby-dev build-essential

Now, we can install tugboat using RubyGems. We will also install system_timer to avoid a repeated notification message later:

sudo gem install tugboat
sudo gem install system_timer

We now have Tugboat installed on our system. Let’s set it up.

<a id=“api_key”></a>How To Generate an API Key


In order for Tugboat to manage your droplets, you will have to authorize it to access your account through the DigitalOcean API interface. This is a simple procedure.

Log into your account on the DigitalOcean website.

Click on API on the left-hand navigation bar in the Control Panel.

You should see a Client ID pre-populated with a value that references your account.

<img style=“border:2px solid black; display:block;margin-left:auto;margin-right:auto” src=“https://assets.digitalocean.com/articles/tugboat/client_id.png” alt =“DigitalOcean Client ID” />

Below this, if you have not set up an API Key yet, you will be told to generate a key:

<img style=“border:2px solid black; display:block;margin-left:auto;margin-right:auto” src=“https://assets.digitalocean.com/articles/tugboat/generate_key.png” alt =“DigitalOcean Generate Key” />

Your API key will be generated. Copy this key to a secure location. It will not be available to you again once you click out of this page. You will need to regenerate the key if you lose it.

You need both the Client ID and the API key to configure Tugboat, so keep this window open.

<a id=“config”></a>Initial Tugboat Configuration


Tugboat includes an initial configuration command that can be called by typing:

tugboat authorize

You will be asked a series of questions that are necessary to associate tugboat with your DigitalOcean account.

For the first two questions, copy and paste the values from the API page that you have opened:

<pre> Enter your client key: <span class=“highlight”>Client_ID_from_API_page</span> Enter your API key: <span class=“highlight”>API_Key_from_API_page</span> </pre>

The next three questions involve the SSH authorization details necessary to connect to all of your droplets.

Press Enter to accept the default SSH key path. Depending on how you usually connect to your other droplets, you may wish to change the SSH user to another value (such as root). Press Enter to accept the default SSH port unless you connect to your droplets using a different port.

<pre> Enter your SSH key path (optional, defaults to ~/.ssh/id_rsa): Enter your SSH user (optional, defaults to demo): <span class=“highlight”>root</span> Enter your SSH port number (optional, defaults to 22): </pre>

Next, you will be taken through the default settings that will be used for new droplet creation. For now, we will press Enter through these prompts to accept the default values.

Enter your default region ID (optional, defaults to 1 (New York)): 
Enter your default image ID (optional, defaults to 284203 (Ubuntu 12.04 x64)): 
Enter your default size ID (optional, defaults to 66 (512MB)): 
Enter your default ssh key ID (optional, defaults to none): 

You should receive a reply confirming that your keys were accepted:

Authentication with DigitalOcean was successful.

The selections that we have just made are stored in a hidden file in your home directory called .tugboat:

nano ~/.tugboat

---
authentication:
  client_key: xxxxxxxxxxxxxxxxxxxxxx
  api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
defaults:
  ssh_key: ""
  size: "66"
  image: "284203"
  region: "1"
ssh:
  ssh_port: "22"
  ssh_user: root
  ssh_key_path: /home/demo/.ssh/id_rsa

If you ever need to re-generate your API Key, you will need to change it here after you re-generate it on the DigitalOcean website.

Afterwards, you will want to re-verify that the application can associate correctly by typing:

tugboat verify

The SSH section should be self-explanatory if you choose to modify it.

We will cover how to find the information needed to change the defaults section later.

<a id=“connect”></a>Connect to a Droplet


We now have enough configured to explore Tugboat.

Every tugboat command begins with tugboat followed by an action.

Let’s list the droplets that we have in our account:

tugboat droplets

irssi (ip: xxx.xxx.xxx.xx, status: active, region: 1, id: 3150xx)
tug (ip: xxx.xxx.xxx.xxx, status: active, region: 4, id: 3372xx)
test (ip: xxx.xxx.xxx.xx, status: active, region: 4, id: 3373xx)
DigitalOcean20Dollar (ip: xxx.xxx.xxx.xxx, status: active, region: 4, id: 3520xx)
archtestmail (ip: xxx.xxx.xxx.xx, status: active, region: 4, id: 4328xx)
TugWrite (ip: xxx.xxx.xxx.xxx, status: active, region: 4, id: 4496xx)

This is analogous to your droplet’s screen in the web interface. It lists each droplet that we can interact with.

Let’s SSH into one of our droplets by using tugboat:

tugboat ssh ourDroplet

Droplet fuzzy name provided. Finding droplet ID...done, 3150xx (ourDroplet)
Executing SSH (ourDroplet)...
Warning: Identity file /home/demo/.ssh/id_rsa not accessible: No such file or directory.
root@xxx.xxx.xxx.xx's password:

As you can see, we are asked for the password to root@ourDroplet. If we had set up SSH keys, we would have been connected without needing any additional interaction.

Exit out of the droplet to get back into the Tugboat droplet.

A feature that is present throughout the Tugboat experience is “Fuzzy name matching”. This means that Tugboat will recognize any command that is unambiguous enough.

For instance, we could have reached the same result by typing:

tugboat drop

Tugboat will expand drop to mean droplets and execute it without any additional input.

This works with droplet names as well.

<a id=“management”></a>Droplet Management


All of the tasks that you normally accomplish with the Control Panel can be done with Tugboat.

<a id=“get_info”></a>Retrieve Droplet Information


To get more information about a specific droplet, type:

<pre> tugboat info <span class=“highlight”>droplet_name</span> </pre>

Name:             irssi
ID:               3150xx
Status:           active
IP:               xxx.xxx.xxx.xx
Region ID:        1
Image ID:         479972
Size ID:          66
Backups Active:   false

This is mostly the same information that we are given in-line with the droplets command, but there are some additional fields, such as the Image ID, Size ID, and whether backups are enabled.

<a id=“power_management”></a>Droplet Power Management


We can control the power-on state of our droplets by issuing the appropriate commands.

To boot a droplet that is currently down, type:

<pre> tugboat start <span class=“highlight”>droplet_name</span> </pre>

To reboot a droplet, type:

<pre> tugboat restart <span class=“highlight”>droplet_name</span> </pre>

To power down a droplet, type:

<pre> tugboat halt <span class=“highlight”>droplet_name</span> </pre>

<a id=“create_destroy”></a>Droplet Creation and Destruction


Droplets can be deleted by simply typing:

<pre> tugboat destroy <span class=“highlight”>droplet_name</span> </pre>

Because this has irreversible consequences, you are asked to confirm the action before the droplet is destroyed:

Droplet fuzzy name provided. Finding droplet ID...done, 4530xx (blahblah)
Warning! Potentially destructive action. Please confirm [y/n]:

Type y and Enter to destroy the droplet.

To create a droplet, you can use the following syntax:

<pre> tugboat create <span class=“highlight”>droplet_name</span> </pre>

Without additional arguments, your droplet will be created according to the criteria in the default section of your ~/.tugboat file.

We can modify this behavior by passing some optional flags. Use the “help” command with the “create” action as an additional argument to get the usage details of create:

tugboat help create

Usage:
  tugboat create NAME

Options:
  -k, [--keys=KEYS]  # A comma separated list of SSH key ids to add to the droplet
  -s, [--size=N]     # The size_id of the droplet
  -r, [--region=N]   # The region_id of the droplet
  -i, [--image=N]    # The image_id of the droplet

Create a droplet.

As you can see, we can embed any of the SSH keys that we have uploaded to the site, and specify the size, region, and base image for the creation process.

We will discuss how to find the appropriate values for these parameters below.

<a id=“creation_settings”></a>Droplet Creation Settings


We can choose the settings that we want to use for droplet creation by querying the site for the available options.

To see the list of sizes and their associated IDs, type:

tugboat sizes

Sizes:
512MB (id: 66)
1GB (id: 63)
2GB (id: 62)
4GB (id: 64)
8GB (id: 65)
16GB (id: 61)
32GB (id: 60)
48GB (id: 70)
64GB (id: 69)
96GB (id: 68)

As you can see, each size is associated with an id, which we use to reference that value.

So if we wanted to create a 2GB droplet, we could issue the following command:

<pre> tugboat create -s 62 <span class=“highlight”>droplet_name</span> </pre>

A similar command is available to see the available regions:

tugboat regions

Regions:
New York 1 (id: 1)
Amsterdam 1 (id: 2)
San Francisco 1 (id: 3)
New York 2 (id: 4)

Embedding an uploaded SSH key within a new droplet is easy. You can find them by issuing:

tugboat keys

SSH Keys:
Work key (id: 12345)
Home key (id: 56789)

The command to view the available images is slightly more complex, only because by default, it shows the snapshots that you have saved:

tugboat images

My Images:
Ubuntu Basic setup (id: 4799xx, distro: Ubuntu)
Arch default (id: 4811xx, distro: Arch Linux)
LAMP Ubuntu (id: 4908xx, distro: Ubuntu)
LAMP Success (id: 5838xx, distro: CentOS)

You can select any of these to use as a base image by using the associated ID.

To get a more complete list, including all of the pre-configured distro and application images, add the global flag:

tugboat images -g

My Images:
. . .

Global Images:
CentOS 5.8 x64 (id: 1601, distro: CentOS)
CentOS 5.8 x32 (id: 1602, distro: CentOS)
Debian 6.0 x64 (id: 12573, distro: Debian)
Debian 6.0 x32 (id: 12575, distro: Debian)
. . .

You will see a large list of available images. These are referenced by their ID as well, just like the other settings.

These are the pieces of information that we would need to alter the values of the “default” settings in the ~/.tugboat configuration file.

<a id=“misc_admin”></a>Miscellaneous Administration


To take a snapshot using the snapshot command, type:

<pre> tugboat snapshot <span class=“highlight”>name_of_snapshot</span> <span class=“highlight”>droplet_to_snapshot</span> </pre>

To resize a droplet, you need to supply the new size criteria to the resize command. Your droplet must be powered on to run this successfully:

<pre> tugboat resize <span class=“highlight”>droplet_name</span> -s <span class=“highlight”>size_ID</span> </pre>

To reset the root password on a droplet, simply issue the password-reset command:

<pre> tugboat password-reset <span class=“highlight”>droplet_name</span> </pre>

You will receive an email with the new password that has been set for the droplet.

<a id=“help”></a>How To Use the Help System


Tugboat includes a great help system. You can access the general help at any time by typing:

tugboat help

This will give you a list of every command that you can use.

To get more fine-grained help, specify a command name after help.

For instance, to get help with the authorize command, type:

tugboat help authorize

<a id=“other”></a>Other Considerations


<a id=“ssh_keys”></a>How To Set Up SSH Keys


Like most applications that utilize SSH, Tugboat benefits from properly configured SSH keys.

If you have already created a public and private key pair and uploaded the public key to your DigitalOcean page to use for droplet creation, you can copy the private key to your Tugboat droplet.

To do this, log into the computer that you use to access your DigitalOcean droplets. Change to your ssh configuration directory:

cd ~/.ssh

Use scp to copy the private key to the Tugboat droplet:

<pre> scp id_rsa <span class=“highlight”>tugboat_username</span>@<span class=“highlight”>tugboat_droplet_ip</span>:/home/<span class=“highlight”>tugboat_username</span>/.ssh/ </pre>

Log into your Tugboat droplet. Change the ownership of the id_rsa file to match the username you are using with Tugboat.

<pre> sudo chown <span class=“highlight”>tugboat_username</span>:<span class=“highlight”>tugboat_username</span> ~/.ssh/id_rsa </pre>

You should now be able to connect to droplets that have been created with that key without a password:

<pre> tugboat ssh <span class=“highlight”>example_droplet</span> </pre>

Remember to alter your configuration file to use this key for new droplet creation!

If you have not already done so, follow this article to set up key pairs and uploaded a public key to your DigitalOcean page.

<a id=“using_screen”></a>How To Use Screen with Tugboat


One tool that is incredibly useful with Tugboat is screen, a terminal multiplexer.

Put simply, this tool allows you to manage multiple terminal sessions from a single window. You can create and switch between several “windows”, each of which is an independent shell session.

This is especially handy when dealing with multiple SSH sessions, which is exactly what Tugboat allows you to do.

Install screen on Ubuntu by typing:

sudo apt-get update
sudo apt-get install screen

Start the application by typing:

screen

You now are using a terminal session that is actually operating within screen.

You can connect to a droplet here by typing:

<pre> tugboat ssh <span class=“highlight”>droplet1</span> </pre>

Now, create a new window by typing:

Ctrl-a c

That is, hold the control key, and hit the a key, followed by the c key. This creates a new window.

Connect to a new droplet in this window by typing:

<pre> tugboat ssh <span class=“highlight”>droplet2</span> </pre>

You can switch between the windows by typing:

Ctrl-a n

You can destroy windows by typing:

Ctrl-a k

To learn more about how to use screen, click here. To learn how to use tmux, a similar terminal multiplexer, click here.

<a id=“conclusion”></a>Conclusion


Tugboat is a great tool for managing your droplets without ever having to leave a terminal environment. It provides a unified interface to keep track of your droplets and manage your sessions.

Configuring Tugboat correctly eliminates the hassle of having to either perform continuous maintenance on a hosts file or flip back and forth between terminal and browser windows.

If you find any issues with the software or wish to contribute to the project, please visit the Tugboat page on Github.

Thank you Jack Pearkes and the Tugboat team for providing the DigitalOcean community with such a valuable tool!

<div class=“author”>By Justin Ellingwood</div>

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about us


About the authors

Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?
 
8 Comments


This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

And if you are using Oh My Zsh there is a custom plugin for tugboat at https://github.com/DimitriSteyaert/Zsh-tugboat

Tugboat is quite cool, but it looks like it doesn’t support mosh out of the box. So I wrote a little script that sort of hacks this functionality:

ip=$(tugboat info $1 | grep -Eo '[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}')
mosh root@$ip```

Save it something like tugboat-mosh.sh, chmod +x it, and then add it optionally to your bash profile so that you can call it up via 'tugboat-mosh' for example. If anyone has a better idea, please don't hesitate to suggest - I've been playing with tugboat with all of 15 minutes and I'm hardly a bash expert either.

Is the ability to pass userdata available, or will it be available in tugboat?

strange, but my last comment was trimmed, and I can not edit that… here is the full version: Somebody should mention that system_timer gem is only needed, if you are running ruby less than 1.9.0

Nevermind, it’s been fixed.

Tugboat is not working now, please fix

Kamal Nasser
DigitalOcean Employee
DigitalOcean Employee badge
September 14, 2013

@Shelby: You can run <pre>tugboat images -g</pre> to get a listing of all images and their IDs.

Very cool. Is there a listing of the available default images? This looks to default to Ubuntu 12.04 x64, what would the default image ID be for Ubuntu 13.04 x64?

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel